Telnyx Voice Advanced - 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

Join AI Assistant Conversation

Add a participant to an existing AI assistant conversation. Use this command to bring an additional call leg into a running AI conversation.

POST /calls/{call_control_id}/actions/ai_assistant_join

conversation_id

participant

Optional:

client_state

command_id

	response, err := client.Calls.Actions.JoinAIAssistant(
		context.Background(),
		"call_control_id",
		telnyx.CallActionJoinAIAssistantParams{
			ConversationID: "v3:abc123",
			Participant: telnyx.CallActionJoinAIAssistantParamsParticipant{
				ID:   "v3:abc123def456",
				Role: "user",
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", response.Data)

Returns:

conversation_id

result

Update client state

Updates client state

PUT /calls/{call_control_id}/actions/client_state_update

client_state

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

Returns:

result

Send DTMF

Sends DTMF tones from this leg. DTMF tones will be heard by the other end of the call. Expected Webhooks:

There are no webhooks associated with this command.

POST /calls/{call_control_id}/actions/send_dtmf

digits

Optional:

client_state

command_id

duration_millis

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

Returns:

result

SIPREC start

Start siprec session to configured in SIPREC connector SRS.

Expected Webhooks:

• siprec.started

• siprec.stopped

• siprec.failed

POST /calls/{call_control_id}/actions/siprec_start

Optional:

client_state

connector_name

include_metadata_custom_headers

secure

session_timeout_secs

sip_transport

siprec_track

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

Returns:

result

SIPREC stop

Stop SIPREC session. Expected Webhooks:

• siprec.stopped

POST /calls/{call_control_id}/actions/siprec_stop

Optional:

client_state

command_id

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

Returns:

result

Noise Suppression Start (BETA)

POST /calls/{call_control_id}/actions/suppression_start

Optional:

client_state

command_id

direction

noise_suppression_engine

noise_suppression_engine_config

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

Returns:

result

Noise Suppression Stop (BETA)

POST /calls/{call_control_id}/actions/suppression_stop

Optional:

client_state

command_id

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

Returns:

result

Switch supervisor role

Switch the supervisor role for a bridged call. This allows switching between different supervisor modes during an active call

POST /calls/{call_control_id}/actions/switch_supervisor_role

role

	response, err := client.Calls.Actions.SwitchSupervisorRole(
		context.Background(),
		"call_control_id",
		telnyx.CallActionSwitchSupervisorRoleParams{
			Role: telnyx.CallActionSwitchSupervisorRoleParamsRoleBarge,
		},
	)
	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()

callConversationEnded

callConversationInsightsGenerated

callDtmfReceived

callMachineDetectionEnded

callMachineGreetingEnded

callMachinePremiumDetectionEnded

callMachinePremiumGreetingEnded

callReferCompleted

callReferFailed

callReferStarted

callSiprecFailed

callSiprecStarted

callSiprecStopped

Webhook payload fields

callConversationEnded

data.record_type

data.event_type

data.id

data.occurred_at

data.created_at

data.payload.assistant_id

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.calling_party_type

data.payload.conversation_id

data.payload.duration_sec

data.payload.from

data.payload.to

data.payload.llm_model

data.payload.stt_model

data.payload.tts_provider

data.payload.tts_model_id

data.payload.tts_voice_id

callConversationInsightsGenerated

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.calling_party_type

data.payload.insight_group_id

data.payload.results

callDtmfReceived

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.from

data.payload.to

data.payload.digit

callMachineDetectionEnded

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.from

data.payload.to

data.payload.result

callMachineGreetingEnded

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.from

data.payload.to

data.payload.result

callMachinePremiumDetectionEnded

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.from

data.payload.to

data.payload.result

callMachinePremiumGreetingEnded

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.from

data.payload.to

data.payload.result

callReferCompleted

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.connection_id

data.payload.client_state

data.payload.from

data.payload.sip_notify_response

data.payload.to

callReferFailed

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.connection_id

data.payload.client_state

data.payload.from

data.payload.sip_notify_response

data.payload.to

callReferStarted

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.connection_id

data.payload.client_state

data.payload.from

data.payload.sip_notify_response

data.payload.to

callSiprecFailed

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_cause

callSiprecStarted

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

callSiprecStopped

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.hangup_cause