telnyx-voice-advanced-python

Telnyx Voice Advanced - Python

Installation

pip install telnyx

Setup

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

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 telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    # 429: rate limited — wait and retry with exponential backoff
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("Validation error — check required fields and formats")

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

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 — Required: conversation_id, participant

Optional: client_state (string), command_id (string)

response = client.calls.actions.join_ai_assistant(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    conversation_id="v3:abc123",
    participant={
        "id": "v3:abc123def456",
        "role": "user",
    },
)
print(response.data)

Returns: conversation_id (uuid), result (string)

Update client state

Updates client state

PUT /calls/{call_control_id}/actions/client_state_update — Required: client_state

response = client.calls.actions.update_client_state(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    client_state="aGF2ZSBhIG5pY2UgZGF5ID1d",
)
print(response.data)

Returns: result (string)

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 — Required: digits

Optional: client_state (string), command_id (string), duration_millis (int32)

response = client.calls.actions.send_dtmf(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    digits="1www2WABCDw9",
)
print(response.data)

Returns: result (string)

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 (string), connector_name (string), include_metadata_custom_headers (boolean), secure (boolean), session_timeout_secs (integer), sip_transport (enum: udp, tcp, tls), siprec_track (enum: inbound_track, outbound_track, both_tracks)

response = client.calls.actions.start_siprec(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns: result (string)

SIPREC stop

Stop SIPREC session. Expected Webhooks:

• siprec.stopped

POST /calls/{call_control_id}/actions/siprec_stop

Optional: client_state (string), command_id (string)

response = client.calls.actions.stop_siprec(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns: result (string)

Noise Suppression Start (BETA)

POST /calls/{call_control_id}/actions/suppression_start

Optional: client_state (string), command_id (string), direction (enum: inbound, outbound, both), noise_suppression_engine (enum: Denoiser, DeepFilterNet, Krisp, AiCoustics), noise_suppression_engine_config (object)

response = client.calls.actions.start_noise_suppression(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns: result (string)

Noise Suppression Stop (BETA)

POST /calls/{call_control_id}/actions/suppression_stop

Optional: client_state (string), command_id (string)

response = client.calls.actions.stop_noise_suppression(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)

Returns: result (string)

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 — Required: role

response = client.calls.actions.switch_supervisor_role(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    role="barge",
)
print(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 (e.g., Flask — use raw body, not parsed JSON):
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)  # raw body as string
    headers = dict(request.headers)
    try:
        event = client.webhooks.unwrap(payload, headers=headers)
    except Exception as e:
        print(f"Webhook verification failed: {e}")
        return "Invalid signature", 400
    # Signature valid — event is the parsed webhook payload
    print(f"Received event: {event.data.event_type}")
    return "OK", 200

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
callConversationEnded	Call Conversation Ended
callConversationInsightsGenerated	Call Conversation Insights Generated
callDtmfReceived	Call Dtmf Received
callMachineDetectionEnded	Call Machine Detection Ended
callMachineGreetingEnded	Call Machine Greeting Ended
callMachinePremiumDetectionEnded	Call Machine Premium Detection Ended
callMachinePremiumGreetingEnded	Call Machine Premium Greeting Ended
callReferCompleted	Call Refer Completed
callReferFailed	Call Refer Failed
callReferStarted	Call Refer Started
callSiprecFailed	Call Siprec Failed
callSiprecStarted	Call Siprec Started
callSiprecStopped	Call Siprec Stopped

Webhook payload fields

callConversationEnded

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.conversation.ended	The type of event being delivered.
data.id	uuid	Unique identifier for the event.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.created_at	date-time	Timestamp when the event was created in the system.
data.payload.assistant_id	string	Unique identifier of the assistant involved in the call.
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 leg.
data.payload.call_session_id	string	ID that is unique to the call session (group of related call legs).
data.payload.client_state	string	Base64-encoded state received from a command.
data.payload.calling_party_type	enum: pstn, sip	The type of calling party connection.
data.payload.conversation_id	string	ID unique to the conversation or insight group generated for the call.
data.payload.duration_sec	integer	Duration of the conversation in seconds.
data.payload.from	string	The caller's number or identifier.
data.payload.to	string	The callee's number or SIP address.
data.payload.llm_model	string	The large language model used during the conversation.
data.payload.stt_model	string	The speech-to-text model used in the conversation.
data.payload.tts_provider	string	The text-to-speech provider used in the call.
data.payload.tts_model_id	string	The model ID used for text-to-speech synthesis.
data.payload.tts_voice_id	string	Voice ID used for TTS.

callConversationInsightsGenerated

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.conversation_insights.generated	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.calling_party_type	enum: pstn, sip	The type of calling party connection.
data.payload.insight_group_id	string	ID that is unique to the insight group being generated for the call.
data.payload.results	array[object]	Array of insight results being generated for the call.

callDtmfReceived

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.dtmf.received	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	Identifies the type of resource.
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.from	string	Number or SIP URI placing the call.
data.payload.to	string	Destination number or SIP URI of the call.
data.payload.digit	string	The received DTMF digit or symbol.

callMachineDetectionEnded

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.machine.detection.ended	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.from	string	Number or SIP URI placing the call.
data.payload.to	string	Destination number or SIP URI of the call.
data.payload.result	enum: human, machine, not_sure	Answering machine detection result.

callMachineGreetingEnded

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.machine.greeting.ended	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.from	string	Number or SIP URI placing the call.
data.payload.to	string	Destination number or SIP URI of the call.
data.payload.result	enum: beep_detected, ended, not_sure	Answering machine greeting ended result.

callMachinePremiumDetectionEnded

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.machine.premium.detection.ended	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.from	string	Number or SIP URI placing the call.
data.payload.to	string	Destination number or SIP URI of the call.
data.payload.result	enum: human_residence, human_business, machine, silence, fax_detected, not_sure	Premium Answering Machine Detection result.

callMachinePremiumGreetingEnded

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.machine.premium.greeting.ended	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.from	string	Number or SIP URI placing the call.
data.payload.to	string	Destination number or SIP URI of the call.
data.payload.result	enum: beep_detected, no_beep_detected	Premium Answering Machine Greeting Ended result.

callReferCompleted

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.refer.completed	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 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.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.client_state	string	State received from a command.
data.payload.from	string	Number or SIP URI placing the call.
data.payload.sip_notify_response	integer	SIP NOTIFY event status for tracking the REFER attempt.
data.payload.to	string	Destination number or SIP URI of the call.

callReferFailed

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.refer.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	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.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.client_state	string	State received from a command.
data.payload.from	string	Number or SIP URI placing the call.
data.payload.sip_notify_response	integer	SIP NOTIFY event status for tracking the REFER attempt.
data.payload.to	string	Destination number or SIP URI of the call.

callReferStarted

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.refer.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	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.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.client_state	string	State received from a command.
data.payload.from	string	Number or SIP URI placing the call.
data.payload.sip_notify_response	integer	SIP NOTIFY event status for tracking the REFER attempt.
data.payload.to	string	Destination number or SIP URI of the call.

callSiprecFailed

Field	Type	Description
data.record_type	enum: event	Identifies the resource.
data.event_type	enum: siprec.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_cause	string	Q850 reason why siprec session failed.

callSiprecStarted

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: siprec.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.

callSiprecStopped

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: siprec.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.hangup_cause	string	Q850 reason why the SIPREC session was stopped.