Telnyx Voice Streaming - curl

Installation

text

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

Setup

bash

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use

$TELNYX_API_KEY

for authentication.

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

# 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:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

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)

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)

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)

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)

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)

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)

Webhooks

Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

and

telnyx-timestamp

headers. Always verify signatures in production:

bash

# Telnyx signs webhooks with Ed25519 (asymmetric — NOT HMAC/Standard Webhooks).
# Headers sent with each webhook:
#   telnyx-signature-ed25519: base64-encoded Ed25519 signature
#   telnyx-timestamp: Unix timestamp (reject if >5 minutes old for replay protection)
#
# Get your public key from: Telnyx Portal > Account Settings > Keys & Credentials
# 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).
# 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 payload fields

callForkStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.fork.started	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.stream_type`	enum: decrypted	Type of media streamed.

callForkStopped

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.fork.stopped	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_control_id`	string	Unique ID for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.stream_type`	enum: decrypted	Type of media streamed.

callStreamingFailed

Field	Type	Description
`data.record_type`	enum: event	Identifies the resource.
`data.event_type`	enum: streaming.failed	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.failure_reason`	string	A short description explaning why the media streaming failed.
`data.payload.stream_id`	uuid	Identifies the streaming.
`data.payload.stream_type`	enum: websocket, dialogflow	The type of stream connection the stream is performing.

callStreamingStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: streaming.started	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.stream_url`	string	Destination WebSocket address where the stream is going to be delivered.

callStreamingStopped

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: streaming.stopped	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Call ID used to issue commands via Call Control API.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	State received from a command.
`data.payload.stream_url`	string	Destination WebSocket address where the stream is going to be delivered.

transcription

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.transcription	The type of event being delivered.
`data.id`	uuid	Identifies the type of resource.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.payload.call_control_id`	string	Unique identifier and token for controlling the call.
`data.payload.call_leg_id`	string	ID that is unique to the call and can be used to correlate webhook events.
`data.payload.call_session_id`	string	ID that is unique to the call session and can be used to correlate webhook events.
`data.payload.client_state`	string	Use this field to add state to every subsequent webhook.
`data.payload.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.

telnyx-voice-streaming-curl

NPX Install

Tags

SKILL.md Content

Telnyx Voice Streaming - curl

Installation

Setup

Error Handling

Forking start

Forking stop

Streaming start

Streaming stop

Transcription start

Transcription stop

Webhooks

Webhook Verification

Webhook payload fields