用途:用 Python 让 Telnyx AI 助手拨打任意电话号码,覆盖从购买号码到触发呼叫的完整设置。
安装:pip install telnyx requests;使用 import os; from telnyx import Telnyx; client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))。
前提条件(缺一即报特定错误):已购买 Telnyx 号码、TeXML 应用、号码已分配给该 TeXML 应用、目标国家已加入出站语音配置文件白名单、AI 助手的 telephony_settings.default_texml_app_id 指向该 TeXML 应用。模型可用性因账户而异,若返回 422 “not available for inference”,可遍历 client.ai.assistants.list().data 打印 a.model 查找可用模型;常见有 openai/gpt-4o、Qwen/Qwen3-235B-A22B。
主要步骤:1) 购买号码,用 client.available_phone_numbers.list() 与 client.number_orders.create(),再查询订单状态为 success;2) 创建 TeXML 应用 client.texml_applications.create(friendly_name, voice_url),其 ID 同时用作号码分配的 connection_id;3) 用 requests.patch 将号码分配到 https://api.telnyx.com/v2/phone_numbers/{phone} 的 connection_id;4) 获取并更新出站语音配置文件,白名单目标国家(ISO 3166-1 alpha-2),再将该配置文件绑定到 TeXML 应用的 outbound.outbound_voice_profile_id;5) 创建 AI 助手,设置 name、model、instructions、greeting 及 telephony_settings.default_texml_app_id,已有助手可用 client.ai.assistants.update() 补充电话设置;6) 用 client.ai.assistants.scheduled_events.create() 触发外呼,必填 assistant_id、telnyx_conversation_channel="phone_call"、telnyx_end_user_target(被叫 E.164)、telnyx_agent_target(主叫号码,须已分配 TeXML 应用)、scheduled_at_fixed_datetime(UTC ISO 8601,立即呼叫可设为约 5 秒后),可选 dynamic_variables、conversation_metadata。
适用场景:AI 助手主动拨打用户电话的外呼流程搭建。
限制与排查:默认仅美国、加拿大白名单,呼叫其他国家未加白名单返回 403 错误码 D13;缺少 telephony_settings 返回 400 “Assistant does not have telephony settings configured”;TeXML 应用未绑定出站语音配置文件返回 400 “Cannot make outbound call with no outbound voice profile”;呼叫一直 pending 需检查时间是否为未来 UTC、主叫号码是否为已购号码、被叫号码是否正确、号码是否已分配 TeXML 应用;模型不可用返回 422。具体资费、地区覆盖、限流等未提供。