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

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

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

rx

tx

POST /calls/{call_control_id}/actions/fork_start

Optional:

client_state

command_id

rx

stream_type

tx

	response, err := client.Calls.Actions.StartForking(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStartForkingParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

result

Forking stop

Stop forking a call. Expected Webhooks:

• call.fork.stopped

POST /calls/{call_control_id}/actions/fork_stop

Optional:

client_state

command_id

stream_type

	response, err := client.Calls.Actions.StopForking(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStopForkingParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

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

command_id

custom_parameters

dialogflow_config

enable_dialogflow

stream_auth_token

stream_bidirectional_codec

stream_bidirectional_mode

stream_bidirectional_sampling_rate

stream_bidirectional_target_legs

stream_codec

stream_track

stream_url

	response, err := client.Calls.Actions.StartStreaming(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStartStreamingParams{
		StreamURL: "wss://example.com/audio-stream",
	},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

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

command_id

stream_id

	response, err := client.Calls.Actions.StopStreaming(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStopStreamingParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

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

command_id

transcription_engine

transcription_engine_config

transcription_tracks

	response, err := client.Calls.Actions.StartTranscription(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStartTranscriptionParams{
			TranscriptionStartRequest: telnyx.TranscriptionStartRequestParam{},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

result

Transcription stop

Stop real-time transcription.

POST /calls/{call_control_id}/actions/transcription_stop

Optional:

client_state

command_id

	response, err := client.Calls.Actions.StopTranscription(
		context.Background(),
		"call_control_id",
		telnyx.CallActionStopTranscriptionParams{},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

result

Webhooks

Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

telnyx-timestamp

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

telnyx-signature-ed25519

client.webhooks.unwrap()

callForkStarted

callForkStopped

callStreamingFailed

callStreamingStarted

callStreamingStopped

transcription

Webhook payload fields

callForkStarted

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.connection_id

data.payload.call_control_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.stream_type

callForkStopped

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.connection_id

data.payload.call_control_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.stream_type

callStreamingFailed

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.call_control_id

data.payload.connection_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.failure_reason

data.payload.stream_id

data.payload.stream_type

callStreamingStarted

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.call_control_id

data.payload.connection_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.stream_url

callStreamingStopped

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.call_control_id

data.payload.connection_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.stream_url

transcription

data.record_type

data.event_type

data.id

data.occurred_at

data.payload.call_control_id

data.payload.call_leg_id

data.payload.call_session_id

data.payload.client_state

data.payload.connection_id