{"id":"2c3cf959-1103-4a75-93af-67d43f1da7d0","shortId":"s2zhMD","kind":"skill","title":"telnyx-ai-outbound-voice-python","tagline":">-","description":"# Telnyx AI Outbound Voice Calls - Python\n\nMake an AI assistant call any phone number. This skill covers the complete\nsetup from purchasing a number to triggering the call.\n\n## Installation\n\n```bash\npip install telnyx requests\n```\n\n## Setup\n\n```python\nimport os\nfrom telnyx import Telnyx\n\nclient = Telnyx(api_key=os.environ.get(\"TELNYX_API_KEY\"))\n```\n\n## Prerequisites\n\nOutbound voice calls require **all** of the following. Missing any one produces\na specific error — see [Troubleshooting](#troubleshooting).\n\n1. A purchased Telnyx phone number\n2. A TeXML application\n3. The phone number assigned to the TeXML application\n4. An outbound voice profile with destination countries whitelisted\n5. An AI assistant with `telephony_settings.default_texml_app_id` set to the TeXML app\n\n## Model availability\n\nModel availability varies by account. If `client.ai.assistants.create()` returns\n422 \"not available for inference\", discover working models from existing assistants:\n\n```python\nfor a in client.ai.assistants.list().data:\n    print(a.model)\n```\n\nCommonly available: `openai/gpt-4o`, `Qwen/Qwen3-235B-A22B`.\n\n## Step 1: Purchase a phone number\n\n```python\nimport time\n\navailable = client.available_phone_numbers.list()\nphone = available.data[0].phone_number\n\nnumber_order = client.number_orders.create(\n    phone_numbers=[{\"phone_number\": phone}],\n)\ntime.sleep(3)\n\norder = client.number_orders.retrieve(number_order.data.id)\nassert order.data.status == \"success\"\nprint(f\"Purchased: {phone}\")\n```\n\n## Step 2: Create a TeXML application\n\nThe `voice_url` is required by the API but is not used for outbound AI assistant calls.\nThe TeXML app ID is also used as the `connection_id` when assigning phone numbers.\n\n```python\ntexml_app = client.texml_applications.create(\n    friendly_name=\"My AI Assistant App\",\n    voice_url=\"https://example.com/placeholder\",\n)\napp_id = texml_app.data.id  # This is also the connection_id for phone number assignment\n```\n\n## Step 3: Assign the phone number to the TeXML application\n\nA phone number cannot make calls until it is assigned to a connection.\n\n```python\nimport requests\n\nrequests.patch(\n    f\"https://api.telnyx.com/v2/phone_numbers/{phone}\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['TELNYX_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json={\"connection_id\": app_id},\n)\n```\n\n## Step 4: Whitelist destination countries\n\nBy default only US and CA are whitelisted. Calling any other country without\nwhitelisting it first returns 403 error code D13.\n\n```python\nimport requests\n\nheaders = {\n    \"Authorization\": f\"Bearer {os.environ['TELNYX_API_KEY']}\",\n    \"Content-Type\": \"application/json\",\n}\n\n# Find the outbound voice profile\nr = requests.get(\n    \"https://api.telnyx.com/v2/outbound_voice_profiles\", headers=headers\n)\novp_id = r.json()[\"data\"][0][\"id\"]\n\n# Add destination countries (ISO 3166-1 alpha-2 codes)\nrequests.patch(\n    f\"https://api.telnyx.com/v2/outbound_voice_profiles/{ovp_id}\",\n    headers=headers,\n    json={\"whitelisted_destinations\": [\"US\", \"CA\", \"IE\", \"GB\"]},\n)\n\n# Assign the profile to the TeXML app\nrequests.patch(\n    f\"https://api.telnyx.com/v2/texml_applications/{app_id}\",\n    headers=headers,\n    json={\n        \"friendly_name\": \"My AI Assistant App\",\n        \"voice_url\": \"https://example.com/placeholder\",\n        \"outbound\": {\"outbound_voice_profile_id\": ovp_id},\n    },\n)\n```\n\n## Step 5: Create the AI assistant with telephony settings\n\n`telephony_settings` with `default_texml_app_id` is **required** for outbound\ncalls. Without it, `scheduled_events.create()` returns 400 \"Assistant does not\nhave telephony settings configured\".\n\n```python\nassistant = client.ai.assistants.create(\n    name=\"My Voice Assistant\",\n    model=\"openai/gpt-4o\",\n    instructions=(\n        \"You are a helpful phone assistant. \"\n        \"Keep your answers concise and conversational since this is a phone call.\"\n    ),\n    greeting=\"Hello! How can I help you today?\",\n    telephony_settings={\"default_texml_app_id\": app_id},\n)\n```\n\nTo add telephony to an existing assistant:\n\n```python\nclient.ai.assistants.update(\n    assistant_id=\"your-assistant-id\",\n    telephony_settings={\"default_texml_app_id\": app_id},\n)\n```\n\n## Step 6: Trigger an outbound call\n\nUse `scheduled_events.create()` with a time a few seconds in the future for\nan immediate call.\n\n```python\nfrom datetime import datetime, timezone, timedelta\n\nevent = client.ai.assistants.scheduled_events.create(\n    assistant_id=assistant.id,\n    telnyx_conversation_channel=\"phone_call\",\n    telnyx_end_user_target=\"+13125550001\",  # Number to call (recipient)\n    telnyx_agent_target=phone,               # Your Telnyx number (caller ID)\n    scheduled_at_fixed_datetime=(\n        datetime.now(timezone.utc) + timedelta(seconds=5)\n    ).isoformat(),\n)\nprint(f\"Status: {event.status}\")  # \"pending\"\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `assistant_id` | string (UUID) | Yes | The AI assistant that handles the call. |\n| `telnyx_conversation_channel` | string | Yes | Must be `\"phone_call\"`. |\n| `telnyx_end_user_target` | string (E.164) | Yes | Phone number to call (recipient). |\n| `telnyx_agent_target` | string (E.164) | Yes | Your Telnyx number (caller ID). Must be assigned to the TeXML app. |\n| `scheduled_at_fixed_datetime` | string (ISO 8601) | Yes | When to place the call. ~5s in the future for immediate. |\n| `dynamic_variables` | object | No | Variables to pass to the assistant. |\n| `conversation_metadata` | object | No | Metadata to attach to the conversation. |\n\n## Complete minimal example\n\n```python\nimport os, time\nfrom datetime import datetime, timezone, timedelta\nfrom telnyx import Telnyx\nimport requests\n\napi_key = os.environ[\"TELNYX_API_KEY\"]\nclient = Telnyx(api_key=api_key)\nheaders = {\"Authorization\": f\"Bearer {api_key}\", \"Content-Type\": \"application/json\"}\n\n# 1. Buy a number\navailable = client.available_phone_numbers.list()\nphone = available.data[0].phone_number\norder = client.number_orders.create(phone_numbers=[{\"phone_number\": phone}])\ntime.sleep(3)\n\n# 2. Create TeXML app\napp = client.texml_applications.create(\n    friendly_name=\"AI Outbound App\",\n    voice_url=\"https://example.com/placeholder\",\n)\napp_id = app.data.id\n\n# 3. Assign number\nrequests.patch(\n    f\"https://api.telnyx.com/v2/phone_numbers/{phone}\",\n    headers=headers,\n    json={\"connection_id\": app_id},\n)\n\n# 4. Configure outbound profile\novp = requests.get(\"https://api.telnyx.com/v2/outbound_voice_profiles\", headers=headers).json()[\"data\"][0]\nrequests.patch(\n    f\"https://api.telnyx.com/v2/outbound_voice_profiles/{ovp['id']}\",\n    headers=headers,\n    json={\"whitelisted_destinations\": [\"US\", \"CA\"]},\n)\nrequests.patch(\n    f\"https://api.telnyx.com/v2/texml_applications/{app_id}\",\n    headers=headers,\n    json={\n        \"friendly_name\": \"AI Outbound App\",\n        \"voice_url\": \"https://example.com/placeholder\",\n        \"outbound\": {\"outbound_voice_profile_id\": ovp[\"id\"]},\n    },\n)\n\n# 5. Create assistant with telephony\nassistant = client.ai.assistants.create(\n    name=\"Outbound Bot\",\n    model=\"openai/gpt-4o\",\n    instructions=\"You are a helpful phone assistant.\",\n    telephony_settings={\"default_texml_app_id\": app_id},\n)\n\n# 6. Trigger call\nclient.ai.assistants.scheduled_events.create(\n    assistant_id=assistant.id,\n    telnyx_conversation_channel=\"phone_call\",\n    telnyx_end_user_target=\"+13125550001\",\n    telnyx_agent_target=phone,\n    scheduled_at_fixed_datetime=(datetime.now(timezone.utc) + timedelta(seconds=5)).isoformat(),\n)\n```\n\n## Troubleshooting\n\n### 400: \"Assistant does not have telephony settings configured\"\n\nThe assistant is missing:\n\n```python\ntelephony_settings={\"default_texml_app_id\": app_id}\n```\n\nFix by updating the assistant with `default_texml_app_id`.\n\n### 400: \"Cannot make outbound call with no outbound voice profile\"\n\nThe TeXML application does not have an outbound voice profile assigned.\n\nFix Step 4 above: patch the TeXML app with:\n\n```python\n\"outbound\": {\"outbound_voice_profile_id\": ovp_id}\n```\n\n### 403 with `detail.code == \"D13\"`\n\nThe destination country is not whitelisted on the outbound voice profile.\n\nFix Step 4 above: add the destination country ISO code to `whitelisted_destinations`.\n\n### Call never starts / remains pending\n\nCheck:\n\n1. `scheduled_at_fixed_datetime` is in the future and in UTC\n2. `telnyx_agent_target` is your purchased Telnyx number\n3. `telnyx_end_user_target` is the recipient number\n4. The purchased number is assigned to the TeXML app\n\n### 422 \"not available for inference\"\n\nThe selected model is not enabled for your account.\n\nList existing assistants to discover working models:\n\n```python\nfor a in client.ai.assistants.list().data:\n    print(a.model)\n```","tags":["telnyx","outbound","voice","python","team-telnyx","agent-skills","ai-coding-agent","claude-code","cpaas","cursor","iot","llm"],"capabilities":["skill","source-team-telnyx","skill-telnyx-ai-outbound-voice-python","topic-agent-skills","topic-ai-coding-agent","topic-claude-code","topic-cpaas","topic-cursor","topic-iot","topic-llm","topic-sdk","topic-sip","topic-sms","topic-speech-to-text","topic-telephony"],"categories":["ai"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/team-telnyx/ai/telnyx-ai-outbound-voice-python","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add team-telnyx/ai","source_repo":"https://github.com/team-telnyx/ai","install_from":"skills.sh"}},"qualityScore":"0.533","qualityRationale":"deterministic score 0.53 from registry signals: · indexed on github topic:agent-skills · 167 github stars · SKILL.md body (8,742 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T12:54:44.561Z","embedding":null,"createdAt":"2026-04-18T22:06:22.526Z","updatedAt":"2026-04-22T12:54:44.561Z","lastSeenAt":"2026-04-22T12:54:44.561Z","tsv":"'+13125550001':563,880 '-1':366 '-2':368 '/placeholder':239,413,762,829 '/v2/outbound_voice_profiles':352,790 '/v2/outbound_voice_profiles/':374,800 '/v2/phone_numbers/':283,773 '/v2/texml_applications/':397,814 '0':164,359,735,795 '1':76,152,727,999 '2':82,188,747,1011 '3':86,176,254,746,766,1020 '3166':365 '4':95,303,782,950,982,1029 '400':446,896,927 '403':324,965 '422':128,1039 '5':104,422,585,837,893 '5s':660 '6':522,864 '8601':653 'a.model':146,1067 'account':124,1052 'add':361,499,984 'agent':569,630,882,1013 'ai':3,8,15,106,207,232,406,425,602,755,822 'alpha':367 'also':215,245 'answer':472 'api':51,55,200,291,337,705,709,713,715,721 'api.telnyx.com':282,351,373,396,772,789,799,813 'api.telnyx.com/v2/outbound_voice_profiles':350,788 'api.telnyx.com/v2/outbound_voice_profiles/':372,798 'api.telnyx.com/v2/phone_numbers/':281,771 'api.telnyx.com/v2/texml_applications/':395,812 'app':111,117,212,227,234,240,300,392,398,408,435,494,496,517,519,646,750,751,757,763,780,815,824,860,862,913,915,925,955,1038 'app.data.id':765 'applic':85,94,192,262,939 'application/json':296,342,726 'assert':180 'assign':90,222,252,255,272,386,642,767,947,1034 'assist':16,107,138,208,233,407,426,447,455,460,469,504,507,511,551,596,603,675,839,842,855,868,897,905,921,1055 'assistant.id':553,870 'attach':682 'author':286,332,718 'avail':119,121,130,148,160,731,1041 'available.data':163,734 'bash':36 'bearer':288,334,720 'bot':846 'buy':728 'ca':312,383,809 'call':11,17,34,60,209,268,315,441,481,526,541,558,566,607,616,627,659,866,875,931,993 'caller':575,638 'cannot':266,928 'channel':556,610,873 'check':998 'client':49,711 'client.ai.assistants.create':126,456,843 'client.ai.assistants.list':143,1064 'client.ai.assistants.scheduled_events.create':550,867 'client.ai.assistants.update':506 'client.available_phone_numbers.list':161,732 'client.number_orders.create':169,739 'client.number_orders.retrieve':178 'client.texml_applications.create':228,752 'code':326,369,989 'common':147 'complet':25,686 'concis':473 'configur':453,783,903 'connect':219,247,275,298,778 'content':294,340,724 'content-typ':293,339,723 'convers':475,555,609,676,685,872 'countri':102,306,318,363,971,987 'cover':23 'creat':189,423,748,838 'd13':327,968 'data':144,358,794,1065 'datetim':544,546,580,650,694,696,888,1003 'datetime.now':581,889 'default':308,433,492,515,858,911,923 'descript':595 'destin':101,305,362,381,807,970,986,992 'detail.code':967 'discov':133,1057 'dynam':666 'e.164':622,633 'enabl':1049 'end':560,618,877,1022 'error':72,325 'event':549 'event.status':590 'exampl':688 'example.com':238,412,761,828 'example.com/placeholder':237,411,760,827 'exist':137,503,1054 'f':184,280,287,333,371,394,588,719,770,797,811 'find':343 'first':322 'fix':579,649,887,917,948,980,1002 'follow':65 'friend':229,403,753,820 'futur':537,663,1007 'gb':385 'greet':482 'handl':605 'header':285,331,353,354,377,378,400,401,717,775,776,791,792,803,804,817,818 'hello':483 'help':467,487,853 'id':112,213,220,241,248,299,301,356,360,376,399,418,420,436,495,497,508,512,518,520,552,576,597,639,764,779,781,802,816,834,836,861,863,869,914,916,926,962,964 'ie':384 'immedi':540,665 'import':43,47,158,277,329,545,690,695,701,703 'infer':132,1043 'instal':35,38 'instruct':463,849 'iso':364,652,988 'isoformat':586,894 'json':297,379,402,777,793,805,819 'keep':470 'key':52,56,292,338,706,710,714,716,722 'list':1053 'make':13,267,929 'metadata':677,680 'minim':687 'miss':66,907 'model':118,120,135,461,847,1046,1059 'must':613,640 'name':230,404,457,754,821,844 'never':994 'number':20,30,81,89,156,166,167,171,173,224,251,258,265,564,574,625,637,730,737,741,743,768,1019,1028,1032 'number_order.data.id':179 'object':668,678 'one':68 'openai/gpt-4o':149,462,848 'order':168,177,738 'order.data.status':181 'os':44,691 'os.environ':289,335,707 'os.environ.get':53 'outbound':4,9,58,97,206,345,414,415,440,525,756,784,823,830,831,845,930,934,944,958,959,977 'ovp':355,375,419,786,801,835,963 'paramet':592 'pass':672 'patch':952 'pend':591,997 'phone':19,80,88,155,162,165,170,172,174,186,223,250,257,264,284,468,480,557,571,615,624,733,736,740,742,744,774,854,874,884 'pip':37 'place':657 'prerequisit':57 'print':145,183,587,1066 'produc':69 'profil':99,347,388,417,785,833,936,946,961,979 'purchas':28,78,153,185,1017,1031 'python':6,12,42,139,157,225,276,328,454,505,542,689,908,957,1060 'qwen/qwen3-235b-a22b':150 'r':348 'r.json':357 'recipi':567,628,1027 'remain':996 'request':40,278,330,704 'requests.get':349,787 'requests.patch':279,370,393,769,796,810 'requir':61,197,438,594 'return':127,323,445 'schedul':577,647,885,1000 'scheduled_events.create':444,528 'second':534,584,892 'see':73 'select':1045 'set':113,429,431,452,491,514,857,902,910 'setup':26,41 'sinc':476 'skill':22 'skill-telnyx-ai-outbound-voice-python' 'source-team-telnyx' 'specif':71 'start':995 'status':589 'step':151,187,253,302,421,521,949,981 'string':598,611,621,632,651 'success':182 'target':562,570,620,631,879,883,1014,1024 'telephoni':428,430,451,490,500,513,841,856,901,909 'telephony_settings.default':109 'telnyx':2,7,39,46,48,50,54,79,290,336,554,559,568,573,608,617,629,636,700,702,708,712,871,876,881,1012,1018,1021 'telnyx-ai-outbound-voice-python':1 'texml':84,93,110,116,191,211,226,261,391,434,493,516,645,749,859,912,924,938,954,1037 'texml_app.data.id':242 'time':159,531,692 'time.sleep':175,745 'timedelta':548,583,698,891 'timezon':547,697 'timezone.utc':582,890 'today':489 'topic-agent-skills' 'topic-ai-coding-agent' 'topic-claude-code' 'topic-cpaas' 'topic-cursor' 'topic-iot' 'topic-llm' 'topic-sdk' 'topic-sip' 'topic-sms' 'topic-speech-to-text' 'topic-telephony' 'trigger':32,523,865 'troubleshoot':74,75,895 'type':295,341,593,725 'updat':919 'url':195,236,410,759,826 'us':310,382,808 'use':204,216,527 'user':561,619,878,1023 'utc':1010 'uuid':599 'vari':122 'variabl':667,670 'voic':5,10,59,98,194,235,346,409,416,459,758,825,832,935,945,960,978 'whitelist':103,304,314,320,380,806,974,991 'without':319,442 'work':134,1058 'yes':600,612,623,634,654 'your-assistant-id':509","prices":[{"id":"001ee951-849f-4502-809c-3f8f63c1fd4e","listingId":"2c3cf959-1103-4a75-93af-67d43f1da7d0","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"team-telnyx","category":"ai","install_from":"skills.sh"},"createdAt":"2026-04-18T22:06:22.526Z"}],"sources":[{"listingId":"2c3cf959-1103-4a75-93af-67d43f1da7d0","source":"github","sourceId":"team-telnyx/ai/telnyx-ai-outbound-voice-python","sourceUrl":"https://github.com/team-telnyx/ai/tree/main/skills/telnyx-ai-outbound-voice-python","isPrimary":false,"firstSeenAt":"2026-04-18T22:06:22.526Z","lastSeenAt":"2026-04-22T12:54:44.561Z"}],"details":{"listingId":"2c3cf959-1103-4a75-93af-67d43f1da7d0","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"team-telnyx","slug":"telnyx-ai-outbound-voice-python","github":{"repo":"team-telnyx/ai","stars":167,"topics":["agent-skills","ai","ai-coding-agent","claude-code","cpaas","cursor","iot","llm","sdk","sip","sms","speech-to-text","telephony","telnyx","tts","twilio-migration","voice-agents","voice-ai","webrtc","windsurf"],"license":"mit","html_url":"https://github.com/team-telnyx/ai","pushed_at":"2026-04-21T22:09:49Z","description":"Official one-stop shop for AI Agents and developers building with Telnyx.","skill_md_sha":"0dd46105bb4902ec465a208fc00b04f8ce6a0b7c","skill_md_path":"skills/telnyx-ai-outbound-voice-python/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/team-telnyx/ai/tree/main/skills/telnyx-ai-outbound-voice-python"},"layout":"multi","source":"github","category":"ai","frontmatter":{"name":"telnyx-ai-outbound-voice-python","description":">-"},"skills_sh_url":"https://skills.sh/team-telnyx/ai/telnyx-ai-outbound-voice-python"},"updatedAt":"2026-04-22T12:54:44.561Z"}}