Back to Details

telnyx-voice-streaming-curl

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 - curl

Telnyx 语音流 - curl

Installation

安装

text
undefined
text
undefined

curl is pre-installed on macOS, Linux, and Windows 10+

curl is pre-installed on macOS, Linux, and Windows 10+

undefined
undefined

Setup

环境配置

bash
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
All examples below use 
$TELNYX_API_KEY
for authentication.
bash
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
以下所有示例都使用
$TELNYX_API_KEY
进行身份验证。

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:
bash
undefined
所有API调用都可能因网络错误、速率限制(429)、校验错误(422)或身份验证错误(401)失败。生产环境代码中请务必做好错误处理：
bash
undefined

Check HTTP status code in response

Check HTTP status code in response

response=$(curl -s -w "\n%{http_code}"
-X POST "https://api.telnyx.com/v2/messages"
-H "Authorization: Bearer $TELNYX_API_KEY"
-H "Content-Type: application/json"
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1) body=$(echo "$response" | sed '$d')
case $http_code in 2*) echo "Success: $body" ;; 422) echo "Validation error — check required fields and formats" ;; 429) echo "Rate limited — retry after delay"; sleep 1 ;; 401) echo "Authentication failed — check TELNYX_API_KEY" ;; *) echo "Error $http_code: $body" ;; esac

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).
response=$(curl -s -w "\n%{http_code}"
-X POST "https://api.telnyx.com/v2/messages"
-H "Authorization: Bearer $TELNYX_API_KEY"
-H "Content-Type: application/json"
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1) body=$(echo "$response" | sed '$d')
case $http_code in 2*) echo "Success: $body" ;; 422) echo "Validation error — check required fields and formats" ;; 429) echo "Rate limited — retry after delay"; sleep 1 ;; 401) echo "Authentication failed — check TELNYX_API_KEY" ;; *) echo "Error $http_code: $body" ;; esac

常见错误码：`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)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/fork_start"
Returns: 
result
(string)
通话分流功能允许你将通话中的媒体实时传输到指定目标。该流可用于实现实时音频分析，支持多种场景，包括欺诈检测，或者生成AI音频响应。请求必须指定
target
属性，或者
rx
和
tx
属性。
POST /calls/{call_control_id}/actions/fork_start
可选参数：
client_state
(字符串), 
command_id
(字符串), 
rx
(字符串), 
stream_type
(枚举: decrypted), 
tx
(字符串)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/fork_start"
返回值：
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)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/fork_stop"
Returns: 
result
(string)
停止通话分流。预期触发的Webhooks：
  • call.fork.stopped
POST /calls/{call_control_id}/actions/fork_stop
可选参数：
client_state
(字符串), 
command_id
(字符串), 
stream_type
(枚举: raw, decrypted)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/fork_stop"
返回值：
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)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "stream_url": "wss://example.com/audio-stream"
  }' \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/streaming_start"
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
(字符串)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "stream_url": "wss://example.com/audio-stream"
  }' \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/streaming_start"
返回值：
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)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/streaming_stop"
Returns: 
result
(string)
停止向WebSocket传输通话流。预期触发的Webhooks：
  • streaming.stopped
POST /calls/{call_control_id}/actions/streaming_stop
可选参数：
client_state
(字符串), 
command_id
(字符串), 
stream_id
(uuid)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/streaming_stop"
返回值：
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)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/transcription_start"
Returns: 
result
(string)
启动实时语音转写。转写将在通话挂断时自动停止，也可以通过转写停止命令手动终止。预期触发的Webhooks：
  • 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
(字符串)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/transcription_start"
返回值：
result
(字符串)

Transcription stop

停止实时转写

Stop real-time transcription.
POST /calls/{call_control_id}/actions/transcription_stop
Optional: 
client_state
(string), 
command_id
(string)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/transcription_stop"
Returns: 
result
(string)
停止实时语音转写。
POST /calls/{call_control_id}/actions/transcription_stop
可选参数：
client_state
(字符串), 
command_id
(字符串)
bash
curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/calls/v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ/actions/transcription_stop"
返回值：
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:
bash
undefined
Telnyx使用Ed25519对Webhooks进行签名。每个请求都包含
telnyx-signature-ed25519
和
telnyx-timestamp
请求头。生产环境中请务必验证签名：
bash
undefined

Telnyx signs webhooks with Ed25519 (asymmetric — NOT HMAC/Standard Webhooks).

Telnyx signs webhooks with Ed25519 (asymmetric — NOT HMAC/Standard Webhooks).

Headers sent with each webhook:

Headers sent with each webhook:

telnyx-signature-ed25519: base64-encoded Ed25519 signature

telnyx-signature-ed25519: base64-encoded Ed25519 signature

telnyx-timestamp: Unix timestamp (reject if >5 minutes old for replay protection)

telnyx-timestamp: Unix timestamp (reject if >5 minutes old for replay protection)

Get your public key from: Telnyx Portal > Account Settings > Keys & Credentials

Get your public key from: Telnyx Portal > Account Settings > Keys & Credentials

Use the Telnyx SDK in your language for verification (client.webhooks.unwrap).

Use the Telnyx SDK in your language for verification (client.webhooks.unwrap).

Your endpoint MUST return 2xx within 2 seconds or Telnyx will retry (up to 3 attempts).

Your endpoint MUST return 2xx within 2 seconds or Telnyx will retry (up to 3 attempts).

Configure a failover URL in Telnyx Portal for additional reliability.

Configure a failover URL in Telnyx Portal for additional reliability.


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.

| Event | Description |
|-------|-------------|
| `callForkStarted` | Call Fork Started |
| `callForkStopped` | Call Fork Stopped |
| `callStreamingFailed` | Call Streaming Failed |
| `callStreamingStarted` | Call Streaming Started |
| `callStreamingStopped` | Call Streaming Stopped |
| `transcription` | Transcription |

以下Webhook事件会发送到你配置的Webhook地址。所有Webhooks都包含`telnyx-timestamp`和`telnyx-signature-ed25519`头用于Ed25519签名验证。你可以使用`client.webhooks.unwrap()`方法进行验证。

| 事件 | 描述 |
|-------|-------------|
| `callForkStarted` | 通话分流已启动 |
| `callForkStopped` | 通话分流已停止 |
| `callStreamingFailed` | 通话流传输失败 |
| `callStreamingStarted` | 通话流传输已启动 |
| `callStreamingStopped` | 通话流传输已停止 |
| `transcription` | 转写结果 |

Webhook payload fields

Webhook payload字段

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标识资源类型。
data.occurred_at
date-time事件发生的ISO 8601格式时间戳。
data.payload.connection_id
字符串通话所使用的Call Control App ID（原Telnyx connection 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标识资源类型。
data.occurred_at
date-time事件发生的ISO 8601格式时间戳。
data.payload.connection_id
字符串通话所使用的Call Control App ID（原Telnyx connection 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标识资源类型。
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 connection 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标识资源类型。
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 connection 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标识资源类型。
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 connection 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标识资源类型。
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 connection ID）。