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:

```python
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.

telnyx-voice-advanced-python

Telnyx Voice Advanced - Python

Installation

Setup

More from team-telnyx/ai

telnyx-numbers-javascript

telnyx-voice-javascript

telnyx-messaging-javascript

telnyx-numbers-config-javascript

telnyx-voice-python

telnyx-voice-streaming-javascript