Telnyx Voice Streaming - Go
Installation
go get github.com/team-telnyx/telnyx-go
Setup
import ( "context" "fmt" "os"
"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )
client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )
All examples below assume client is already initialized as shown above.
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:
import "errors"
result, err := client.Messages.Send(ctx, params) if err != nil { var apiErr *telnyx.Error if errors.As(err, &apiErr) { switch apiErr.StatusCode { case 422: fmt.Println("Validation error — check required fields and formats") case 429: // Rate limited — wait and retry with exponential backoff fmt.Println("Rate limited, retrying...") default: fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Error()) } } else { fmt.Println("Network error — check connectivity and retry") } }
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).
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)
response, err := client.Calls.Actions.StartForking(
context.TODO(),
"call_control_id",
telnyx.CallActionStartForkingParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
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)
response, err := client.Calls.Actions.StopForking(
context.TODO(),
"call_control_id",
telnyx.CallActionStopForkingParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
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)
response, err := client.Calls.Actions.StartStreaming(
context.TODO(),
"call_control_id",
telnyx.CallActionStartStreamingParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
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)
response, err := client.Calls.Actions.StopStreaming(
context.TODO(),
"call_control_id",
telnyx.CallActionStopStreamingParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
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)
response, err := client.Calls.Actions.StartTranscription(
context.TODO(),
"call_control_id",
telnyx.CallActionStartTranscriptionParams{
TranscriptionStartRequest: telnyx.TranscriptionStartRequestParam{},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
Returns: result (string)
Transcription stop
Stop real-time transcription.
POST /calls/{call_control_id}/actions/transcription_stop
Optional: client_state (string), command_id (string)
response, err := client.Calls.Actions.StopTranscription(
context.TODO(),
"call_control_id",
telnyx.CallActionStopTranscriptionParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Data)
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:
// In your webhook handler: func handleWebhook(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) event, err := client.Webhooks.Unwrap(body, r.Header) if err != nil { http.Error(w, "Invalid signature", http.StatusBadRequest) return } // Signature valid — event is the parsed webhook payload fmt.Println("Received event:", event.Data.EventType) w.WriteHeader(http.StatusOK) }
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.