telnyx-ai-outbound-voice-python

Telnyx AI Outbound Voice Calls - Python

Make an AI assistant call any phone number. This skill covers the complete setup from purchasing a number to triggering the call.

Installation

pip install telnyx requests

Setup

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

Prerequisites

Outbound voice calls require all of the following. Missing any one produces a specific error — see Troubleshooting.

1. A purchased Telnyx phone number
2. A TeXML application
3. The phone number assigned to the TeXML application
4. An outbound voice profile with destination countries whitelisted
5. An AI assistant with telephony_settings.default_texml_app_id set to the TeXML app

Model availability

Model availability varies by account. If client.ai.assistants.create() returns 422 "not available for inference", discover working models from existing assistants:

for a in client.ai.assistants.list().data:
    print(a.model)

Commonly available: openai/gpt-4o, Qwen/Qwen3-235B-A22B.

Step 1: Purchase a phone number

import time

available = client.available_phone_numbers.list()
phone = available.data[0].phone_number

number_order = client.number_orders.create(
    phone_numbers=[{"phone_number": phone}],
)
time.sleep(3)

order = client.number_orders.retrieve(number_order.data.id)
assert order.data.status == "success"
print(f"Purchased: {phone}")

Step 2: Create a TeXML application

The voice_url is required by the API but is not used for outbound AI assistant calls. The TeXML app ID is also used as the connection_id when assigning phone numbers.

texml_app = client.texml_applications.create(
    friendly_name="My AI Assistant App",
    voice_url="https://example.com/placeholder",
)
app_id = texml_app.data.id  # This is also the connection_id for phone number assignment

Step 3: Assign the phone number to the TeXML application

A phone number cannot make calls until it is assigned to a connection.

import requests

requests.patch(
    f"https://api.telnyx.com/v2/phone_numbers/{phone}",
    headers={
        "Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"connection_id": app_id},
)

Step 4: Whitelist destination countries

By default only US and CA are whitelisted. Calling any other country without whitelisting it first returns 403 error code D13.

import requests

headers = {
    "Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}",
    "Content-Type": "application/json",
}

# Find the outbound voice profile
r = requests.get(
    "https://api.telnyx.com/v2/outbound_voice_profiles", headers=headers
)
ovp_id = r.json()["data"][0]["id"]

# Add destination countries (ISO 3166-1 alpha-2 codes)
requests.patch(
    f"https://api.telnyx.com/v2/outbound_voice_profiles/{ovp_id}",
    headers=headers,
    json={"whitelisted_destinations": ["US", "CA", "IE", "GB"]},
)

# Assign the profile to the TeXML app
requests.patch(
    f"https://api.telnyx.com/v2/texml_applications/{app_id}",
    headers=headers,
    json={
        "friendly_name": "My AI Assistant App",
        "voice_url": "https://example.com/placeholder",
        "outbound": {"outbound_voice_profile_id": ovp_id},
    },
)

Step 5: Create the AI assistant with telephony settings

telephony_settings with default_texml_app_id is required for outbound calls. Without it, scheduled_events.create() returns 400 "Assistant does not have telephony settings configured".

assistant = client.ai.assistants.create(
    name="My Voice Assistant",
    model="openai/gpt-4o",
    instructions=(
        "You are a helpful phone assistant. "
        "Keep your answers concise and conversational since this is a phone call."
    ),
    greeting="Hello! How can I help you today?",
    telephony_settings={"default_texml_app_id": app_id},
)

To add telephony to an existing assistant:

client.ai.assistants.update(
    assistant_id="your-assistant-id",
    telephony_settings={"default_texml_app_id": app_id},
)

Step 6: Trigger an outbound call

Use scheduled_events.create() with a time a few seconds in the future for an immediate call.

from datetime import datetime, timezone, timedelta

event = client.ai.assistants.scheduled_events.create(
    assistant_id=assistant.id,
    telnyx_conversation_channel="phone_call",
    telnyx_end_user_target="+13125550001",  # Number to call (recipient)
    telnyx_agent_target=phone,               # Your Telnyx number (caller ID)
    scheduled_at_fixed_datetime=(
        datetime.now(timezone.utc) + timedelta(seconds=5)
    ).isoformat(),
)
print(f"Status: {event.status}")  # "pending"

Parameter	Type	Required	Description
assistant_id	string (UUID)	Yes	The AI assistant that handles the call.
telnyx_conversation_channel	string	Yes	Must be "phone_call".
telnyx_end_user_target	string (E.164)	Yes	Phone number to call (recipient).
telnyx_agent_target	string (E.164)	Yes	Your Telnyx number (caller ID). Must be assigned to the TeXML app.
scheduled_at_fixed_datetime	string (ISO 8601)	Yes	When to place the call. ~5s in the future for immediate.
dynamic_variables	object	No	Variables to pass to the assistant.
conversation_metadata	object	No	Metadata to attach to the conversation.

Complete minimal example

import os, time
from datetime import datetime, timezone, timedelta
from telnyx import Telnyx
import requests

api_key = os.environ["TELNYX_API_KEY"]
client = Telnyx(api_key=api_key)
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# 1. Buy a number
available = client.available_phone_numbers.list()
phone = available.data[0].phone_number
order = client.number_orders.create(phone_numbers=[{"phone_number": phone}])
time.sleep(3)

# 2. Create TeXML app
app = client.texml_applications.create(
    friendly_name="AI Outbound App",
    voice_url="https://example.com/placeholder",
)
app_id = app.data.id

# 3. Assign number
requests.patch(
    f"https://api.telnyx.com/v2/phone_numbers/{phone}",
    headers=headers,
    json={"connection_id": app_id},
)

# 4. Configure outbound profile
ovp = requests.get("https://api.telnyx.com/v2/outbound_voice_profiles", headers=headers).json()["data"][0]
requests.patch(
    f"https://api.telnyx.com/v2/outbound_voice_profiles/{ovp['id']}",
    headers=headers,
    json={"whitelisted_destinations": ["US", "CA"]},
)
requests.patch(
    f"https://api.telnyx.com/v2/texml_applications/{app_id}",
    headers=headers,
    json={
        "friendly_name": "AI Outbound App",
        "voice_url": "https://example.com/placeholder",
        "outbound": {"outbound_voice_profile_id": ovp["id"]},
    },
)

# 5. Create assistant with telephony
assistant = client.ai.assistants.create(
    name="Outbound Bot",
    model="openai/gpt-4o",
    instructions="You are a helpful phone assistant.",
    telephony_settings={"default_texml_app_id": app_id},
)

# 6. Trigger call
client.ai.assistants.scheduled_events.create(
    assistant_id=assistant.id,
    telnyx_conversation_channel="phone_call",
    telnyx_end_user_target="+13125550001",
    telnyx_agent_target=phone,
    scheduled_at_fixed_datetime=(datetime.now(timezone.utc) + timedelta(seconds=5)).isoformat(),
)

Troubleshooting

400: "Assistant does not have telephony settings configured"

The assistant is missing:

telephony_settings={"default_texml_app_id": app_id}

Fix by updating the assistant with default_texml_app_id.

400: "Cannot make outbound call with no outbound voice profile"

The TeXML application does not have an outbound voice profile assigned.

Fix Step 4 above: patch the TeXML app with:

"outbound": {"outbound_voice_profile_id": ovp_id}

403 with detail.code == "D13"

The destination country is not whitelisted on the outbound voice profile.

Fix Step 4 above: add the destination country ISO code to whitelisted_destinations.

Call never starts / remains pending

Check:

1. scheduled_at_fixed_datetime is in the future and in UTC
2. telnyx_agent_target is your purchased Telnyx number
3. telnyx_end_user_target is the recipient number
4. The purchased number is assigned to the TeXML app

422 "not available for inference"

The selected model is not enabled for your account.

List existing assistants to discover working models:

for a in client.ai.assistants.list().data:
    print(a.model)