Back to Details

telnyx-voice-streaming-javascript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Voice Streaming - JavaScript

Telnyx 语音流 - JavaScript

Installation

安装

bash
npm install telnyx
bash
npm install telnyx

Setup

初始化配置

javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
All examples below assume 
client
is already initialized as shown above.
javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
以下所有示例均假设
client
已按上述方式完成初始化。

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
Common error codes: 
401
invalid API key, 
403
insufficient permissions, 
404
resource not found, 
422
validation error (check field formats), 
429
rate limited (retry with exponential backoff).
所有API调用都可能因网络错误、速率限制(429)、校验错误(422)或鉴权错误(401)失败。在生产代码中请务必做好错误处理：
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
常见错误码：
401
API密钥无效，
403
权限不足，
404
资源未找到，
422
校验错误（请检查字段格式），
429
触发速率限制（请使用指数退避策略重试）。

Forking start

启动媒体分流

Call forking allows you to stream the media from a call to a specific target in realtime. This stream can be used to enable realtime audio analysis to support a variety of use cases, including fraud detection, or the creation of AI-generated audio responses. Requests must specify either the 
target
attribute or the 
rx
and 
tx
attributes.
POST /calls/{call_control_id}/actions/fork_start
Optional: 
client_state
(string), 
command_id
(string), 
rx
(string), 
stream_type
(enum: decrypted), 
tx
(string)
javascript
const response = await client.calls.actions.startForking('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
通话分流功能允许你将通话中的媒体实时流转到指定目标，该流可用于实现实时音频分析，支撑多种使用场景，包括欺诈检测、生成AI音频响应等。请求必须指定
target
属性，或
rx
和
tx
属性。
POST /calls/{call_control_id}/actions/fork_start
可选参数：
client_state
（字符串）、
command_id
（字符串）、
rx
（字符串）、
stream_type
（枚举值：decrypted）、
tx
（字符串）
javascript
const response = await client.calls.actions.startForking('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Forking stop

停止媒体分流

Stop forking a call. Expected Webhooks:
  • call.fork.stopped
POST /calls/{call_control_id}/actions/fork_stop
Optional: 
client_state
(string), 
command_id
(string), 
stream_type
(enum: raw, decrypted)
javascript
const response = await client.calls.actions.stopForking('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
停止通话分流。预期触发的Webhook：
  • call.fork.stopped
POST /calls/{call_control_id}/actions/fork_stop
可选参数：
client_state
（字符串）、
command_id
（字符串）、
stream_type
（枚举值：raw, decrypted）
javascript
const response = await client.calls.actions.stopForking('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Streaming start

启动媒体流

Start streaming the media from a call to a specific WebSocket address or Dialogflow connection in near-realtime. Audio will be delivered as base64-encoded RTP payload (raw audio), wrapped in JSON payloads. Please find more details about media streaming messages specification under the link.
POST /calls/{call_control_id}/actions/streaming_start
Optional: 
client_state
(string), 
command_id
(string), 
custom_parameters
(array[object]), 
dialogflow_config
(object), 
enable_dialogflow
(boolean), 
stream_auth_token
(string), 
stream_bidirectional_codec
(enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16), 
stream_bidirectional_mode
(enum: mp3, rtp), 
stream_bidirectional_sampling_rate
(enum: 8000, 16000, 22050, 24000, 48000), 
stream_bidirectional_target_legs
(enum: both, self, opposite), 
stream_codec
(enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16, default), 
stream_track
(enum: inbound_track, outbound_track, both_tracks), 
stream_url
(string)
javascript
const response = await client.calls.actions.startStreaming('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
近乎实时地将通话媒体流转到指定WebSocket地址或Dialogflow连接。音频将以base64编码的RTP payload（原始音频）形式封装在JSON payload中传输。你可以通过链接查看媒体流消息规范的更多详情。
POST /calls/{call_control_id}/actions/streaming_start
可选参数：
client_state
（字符串）、
command_id
（字符串）、
custom_parameters
（数组[对象]）、
dialogflow_config
（对象）、
enable_dialogflow
（布尔值）、
stream_auth_token
（字符串）、
stream_bidirectional_codec
（枚举值：PCMU, PCMA, G722, OPUS, AMR-WB, L16）、
stream_bidirectional_mode
（枚举值：mp3, rtp）、
stream_bidirectional_sampling_rate
（枚举值：8000, 16000, 22050, 24000, 48000）、
stream_bidirectional_target_legs
（枚举值：both, self, opposite）、
stream_codec
（枚举值：PCMU, PCMA, G722, OPUS, AMR-WB, L16, default）、
stream_track
（枚举值：inbound_track, outbound_track, both_tracks）、
stream_url
（字符串）
javascript
const response = await client.calls.actions.startStreaming('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Streaming stop

停止媒体流

Stop streaming a call to a WebSocket. Expected Webhooks:
  • streaming.stopped
POST /calls/{call_control_id}/actions/streaming_stop
Optional: 
client_state
(string), 
command_id
(string), 
stream_id
(uuid)
javascript
const response = await client.calls.actions.stopStreaming('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
停止将通话流转到WebSocket。预期触发的Webhook：
  • streaming.stopped
POST /calls/{call_control_id}/actions/streaming_stop
可选参数：
client_state
（字符串）、
command_id
（字符串）、
stream_id
（uuid）
javascript
const response = await client.calls.actions.stopStreaming('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Transcription start

启动实时转写

Start real-time transcription. Transcription will stop on call hang-up, or can be initiated via the Transcription stop command. Expected Webhooks:
  • call.transcription
POST /calls/{call_control_id}/actions/transcription_start
Optional: 
client_state
(string), 
command_id
(string), 
transcription_engine
(enum: Google, Telnyx, Deepgram, Azure, A, B), 
transcription_engine_config
(object), 
transcription_tracks
(string)
javascript
const response = await client.calls.actions.startTranscription('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
启动实时语音转写。转写将在通话挂断时自动停止，也可通过转写停止命令手动终止。预期触发的Webhook：
  • call.transcription
POST /calls/{call_control_id}/actions/transcription_start
可选参数：
client_state
（字符串）、
command_id
（字符串）、
transcription_engine
（枚举值：Google, Telnyx, Deepgram, Azure, A, B）、
transcription_engine_config
（对象）、
transcription_tracks
（字符串）
javascript
const response = await client.calls.actions.startTranscription('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Transcription stop

停止实时转写

Stop real-time transcription.
POST /calls/{call_control_id}/actions/transcription_stop
Optional: 
client_state
(string), 
command_id
(string)
javascript
const response = await client.calls.actions.stopTranscription('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
Returns: 
result
(string)
停止实时语音转写。
POST /calls/{call_control_id}/actions/transcription_stop
可选参数：
client_state
（字符串）、
command_id
（字符串）
javascript
const response = await client.calls.actions.stopTranscription('v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ');

console.log(response.data);
返回值：
result
（字符串）

Webhooks

Webhooks

Webhook Verification

Webhook 验签

Telnyx signs webhooks with Ed25519. Each request includes 
telnyx-signature-ed25519
and 
telnyx-timestamp
headers. Always verify signatures in production:
javascript
// In your webhook handler (e.g., Express — use raw body, not parsed JSON):
app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers,
    });
    // Signature valid — event is the parsed webhook payload
    console.log('Received event:', event.data.event_type);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});
The following webhook events are sent to your configured webhook URL. All webhooks include 
telnyx-timestamp
and 
telnyx-signature-ed25519
headers for Ed25519 signature verification. Use 
client.webhooks.unwrap()
to verify.
EventDescription
callForkStarted
Call Fork Started
callForkStopped
Call Fork Stopped
callStreamingFailed
Call Streaming Failed
callStreamingStarted
Call Streaming Started
callStreamingStopped
Call Streaming Stopped
transcription
Transcription
Telnyx使用Ed25519对Webhook进行签名，每个请求都包含
telnyx-signature-ed25519
和
telnyx-timestamp
请求头。生产环境中请务必验证签名：
javascript
// In your webhook handler (e.g., Express — use raw body, not parsed JSON):
app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers,
    });
    // Signature valid — event is the parsed webhook payload
    console.log('Received event:', event.data.event_type);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});
以下Webhook事件会发送到你配置的Webhook地址。所有Webhook都包含
telnyx-timestamp
和
telnyx-signature-ed25519
头，用于Ed25519签名验证，可使用
client.webhooks.unwrap()
完成验签。
事件描述
callForkStarted
通话分流已启动
callForkStopped
通话分流已停止
callStreamingFailed
通话流转失败
callStreamingStarted
通话流转已启动
callStreamingStopped
通话流转已停止
transcription
转写结果

Webhook payload fields

Webhook 载荷字段

callForkStarted
FieldTypeDescription
data.record_type
enum: eventIdentifies the type of the resource.
data.event_type
enum: call.fork.startedThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_control_id
stringUnique ID for controlling the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringState received from a command.
data.payload.stream_type
enum: decryptedType of media streamed.
callForkStopped
FieldTypeDescription
data.record_type
enum: eventIdentifies the type of the resource.
data.event_type
enum: call.fork.stoppedThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_control_id
stringUnique ID for controlling the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringState received from a command.
data.payload.stream_type
enum: decryptedType of media streamed.
callStreamingFailed
FieldTypeDescription
data.record_type
enum: eventIdentifies the resource.
data.event_type
enum: streaming.failedThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_id
stringCall ID used to issue commands via Call Control API.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringState received from a command.
data.payload.failure_reason
stringA short description explaning why the media streaming failed.
data.payload.stream_id
uuidIdentifies the streaming.
data.payload.stream_type
enum: websocket, dialogflowThe type of stream connection the stream is performing.
callStreamingStarted
FieldTypeDescription
data.record_type
enum: eventIdentifies the type of the resource.
data.event_type
enum: streaming.startedThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_id
stringCall ID used to issue commands via Call Control API.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringState received from a command.
data.payload.stream_url
stringDestination WebSocket address where the stream is going to be delivered.
callStreamingStopped
FieldTypeDescription
data.record_type
enum: eventIdentifies the type of the resource.
data.event_type
enum: streaming.stoppedThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_id
stringCall ID used to issue commands via Call Control API.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringState received from a command.
data.payload.stream_url
stringDestination WebSocket address where the stream is going to be delivered.
transcription
FieldTypeDescription
data.record_type
enum: eventIdentifies the type of the resource.
data.event_type
enum: call.transcriptionThe type of event being delivered.
data.id
uuidIdentifies the type of resource.
data.occurred_at
date-timeISO 8601 datetime of when the event occurred.
data.payload.call_control_id
stringUnique identifier and token for controlling the call.
data.payload.call_leg_id
stringID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id
stringID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state
stringUse this field to add state to every subsequent webhook.
data.payload.connection_id
stringCall Control App ID (formerly Telnyx connection ID) used in the call.
callForkStarted
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: call.fork.started触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）
data.payload.call_control_id
字符串控制通话的唯一ID
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串从命令中传递的状态值
data.payload.stream_type
枚举值: decrypted流转的媒体类型
callForkStopped
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: call.fork.stopped触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）
data.payload.call_control_id
字符串控制通话的唯一ID
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串从命令中传递的状态值
data.payload.stream_type
枚举值: decrypted流转的媒体类型
callStreamingFailed
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: streaming.failed触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.call_control_id
字符串用于通过Call Control API下发命令的通话ID
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串从命令中传递的状态值
data.payload.failure_reason
字符串媒体流转失败的简短说明
data.payload.stream_id
uuid媒体流唯一标识
data.payload.stream_type
枚举值: websocket, dialogflow流连接的类型
callStreamingStarted
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: streaming.started触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.call_control_id
字符串用于通过Call Control API下发命令的通话ID
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串从命令中传递的状态值
data.payload.stream_url
字符串媒体流投递的目标WebSocket地址
callStreamingStopped
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: streaming.stopped触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.call_control_id
字符串用于通过Call Control API下发命令的通话ID
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串从命令中传递的状态值
data.payload.stream_url
字符串媒体流投递的目标WebSocket地址
transcription
字段类型描述
data.record_type
枚举值: event标识资源类型
data.event_type
枚举值: call.transcription触发的事件类型
data.id
uuid资源ID
data.occurred_at
date-time事件发生的ISO 8601格式时间戳
data.payload.call_control_id
字符串控制通话的唯一标识和令牌
data.payload.call_leg_id
字符串通话单路唯一ID，可用于关联Webhook事件
data.payload.call_session_id
字符串通话会话唯一ID，可用于关联Webhook事件
data.payload.client_state
字符串可通过该字段为后续所有Webhook附加状态信息
data.payload.connection_id
字符串通话使用的Call Control App ID（原Telnyx连接ID）