Telnyx Voice Gather Python Agent Skill

>- Collect DTMF input and speech from callers using standard gather or AI-powered gather. Build interactive voice menus and AI voice assistants. This skill provides Python SDK examples.

3k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

201

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/team-telnyx/ai --skill telnyx-voice-gather-python

The instruction itself

15 sections, as written by the author

Telnyx Voice Gather - 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).

Add messages to AI Assistant

Add messages to the conversation started by an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_add_messages

Optional: client_state (string), command_id (string), messages (array[object])

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

Returns: result (string)

Start AI Assistant

Start an AI assistant on the call. Expected Webhooks:

call.conversation.ended
call.conversation_insights.generated

POST /calls/{call_control_id}/actions/ai_assistant_start

Optional: assistant (object), client_state (string), command_id (string), greeting (string), interruption_settings (object), message_history (array[object]), participants (array[object]), send_message_history_updates (boolean), transcription (object), voice (string), voice_settings (object)

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

Returns: conversation_id (uuid), result (string)

Stop AI Assistant

Stop an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_stop

Optional: client_state (string), command_id (string)

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

Returns: result (string)

Gather

Gather DTMF signals to build interactive menus. You can pass a list of valid digits. The Answer command must be issued before the gather command.

POST /calls/{call_control_id}/actions/gather

Optional: client_state (string), command_id (string), gather_id (string), initial_timeout_millis (int32), inter_digit_timeout_millis (int32), maximum_digits (int32), minimum_digits (int32), terminating_digit (string), timeout_millis (int32), valid_digits (string)

response = client.calls.actions.gather(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    minimum_digits=1,
    maximum_digits=4,
)
print(response.data)

Returns: result (string)

Gather stop

Stop current gather. Expected Webhooks:

call.gather.ended

POST /calls/{call_control_id}/actions/gather_stop

Optional: client_state (string), command_id (string)

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

Returns: result (string)

Gather using AI

Gather parameters defined in the request payload using a voice assistant. You can pass parameters described as a JSON Schema object and the voice assistant will attempt to gather these informations.

POST /calls/{call_control_id}/actions/gather_using_ai — Required: parameters

Optional: assistant (object), client_state (string), command_id (string), gather_ended_speech (string), greeting (string), interruption_settings (object), language (object), message_history (array[object]), send_message_history_updates (boolean), send_partial_results (boolean), transcription (object), user_response_timeout_ms (integer), voice (string), voice_settings (object)

response = client.calls.actions.gather_using_ai(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    parameters={
        "properties": "bar",
        "required": "bar",
        "type": "bar",
    },
)
print(response.data)

Returns: conversation_id (uuid), result (string)

Gather using audio

Play an audio file on the call until the required DTMF signals are gathered to build interactive menus. You can pass a list of valid digits along with an 'invalid_audio_url', which will be played back at the beginning of each prompt. Playback will be interrupted when a DTMF signal is received.

POST /calls/{call_control_id}/actions/gather_using_audio

Optional: audio_url (string), client_state (string), command_id (string), inter_digit_timeout_millis (int32), invalid_audio_url (string), invalid_media_name (string), maximum_digits (int32), maximum_tries (int32), media_name (string), minimum_digits (int32), terminating_digit (string), timeout_millis (int32), valid_digits (string)

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

Returns: result (string)

Gather using speak

Convert text to speech and play it on the call until the required DTMF signals are gathered to build interactive menus. You can pass a list of valid digits along with an 'invalid_payload', which will be played back at the beginning of each prompt. Speech will be interrupted when a DTMF signal is received.

POST /calls/{call_control_id}/actions/gather_using_speak — Required: voice, payload

Optional: client_state (string), command_id (string), inter_digit_timeout_millis (int32), invalid_payload (string), language (enum: arb, cmn-CN, cy-GB, da-DK, de-DE, en-AU, en-GB, en-GB-WLS, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hi-IN, is-IS, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, tr-TR), maximum_digits (int32), maximum_tries (int32), minimum_digits (int32), payload_type (enum: text, ssml), service_level (enum: basic, premium), terminating_digit (string), timeout_millis (int32), valid_digits (string), voice_settings (object)

response = client.calls.actions.gather_using_speak(
    call_control_id="550e8400-e29b-41d4-a716-446655440000",
    payload="say this on call",
    voice="male",
)
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 |

|-------|-------------|

| CallAIGatherEnded | Call AI Gather Ended |

| CallAIGatherMessageHistoryUpdated | Call AI Gather Message History Updated |

| CallAIGatherPartialResults | Call AI Gather Partial Results |

| callGatherEnded | Call Gather Ended |

Webhook payload fields

CallAIGatherEnded

| Field | Type | Description |

|-------|------|-------------|

| data.record_type | enum: event | Identifies the type of the resource. |

| data.event_type | enum: call.ai_gather.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 | 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.message_history | array[object] | The history of the messages exchanged during the AI gather |

| data.payload.result | object | The result of the AI gather, its type depends of the parameters provided in the command |

| data.payload.status | enum: valid, invalid | Reflects how command ended. |

CallAIGatherMessageHistoryUpdated

| Field | Type | Description |

|-------|------|-------------|

| data.record_type | enum: event | Identifies the type of the resource. |

| data.event_type | enum: call.ai_gather.message_history_updated | The type of event being delivered. |