telnyx-voice-python

Telnyx Voice - Python 是 Telnyx 提供的 Python SDK，用于以编程方式控制电话呼叫，支持发起和接听呼叫、转移、桥接、采集 DTMF 以及音频流传输，并通过 Webhook 接收实时呼叫事件。

安装与初始化

安装命令：pip install telnyx

初始化方式：

import os
from telnyx import Telnyx

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

主要能力

发起外呼

使用 client.calls.dial()（POST /calls）发起外呼。必填参数包括 to（E.164 格式的被叫号码或 SIP URI）、from_（E.164 格式的主叫号码）、connection_id（Call Control App 的 UUID）。可选参数包括 timeout_secs、billing_group_id、client_state 等。响应中主要字段包括 call_control_id、call_leg_id、call_session_id、is_alive、recording_id、call_duration。

接听来电

使用 client.calls.actions.answer()（POST /calls/{call_control_id}/actions/answer）接听来电。必填参数为 call_control_id。可选参数包括 billing_group_id、client_state、webhook_url 等。响应主要字段包括 result、recording_id。

转移通话

使用 client.calls.actions.transfer()（POST /calls/{call_control_id}/actions/transfer）。必填参数为 to（E.164 格式目标号码或 SIP URI）和 call_control_id。可选参数包括 timeout_secs、client_state、webhook_url 等。响应主要字段为 result。

挂断通话

使用 client.calls.actions.hangup()（POST /calls/{call_control_id}/actions/hangup）。必填参数为 call_control_id。可选参数包括 client_state、command_id、custom_headers。响应主要字段为 result。

桥接通话

使用 client.calls.actions.bridge()（POST /calls/{call_control_id}/actions/bridge）。必填参数包括两个 call_control_id（一个为要桥接的通话，另一个为控制标识）。可选参数包括 client_state、command_id、video_room_id 等。响应主要字段为 result。

拒绝通话

使用 client.calls.actions.reject()（POST /calls/{call_control_id}/actions/reject）。必填参数为 cause（枚举值：CALL_REJECTED、USER_BUSY）和 call_control_id。响应主要字段为 result。

查询通话状态

使用 client.calls.retrieve_status()（GET /calls/{call_control_id}）。响应主要字段包括 call_control_id、call_duration、call_leg_id、call_session_id、client_state、end_time。

列出指定连接的活动通话

使用 client.connections.list_active_calls()（GET /connections/{connection_id}/active_calls）。响应包装中 items 为 page.data，pagination 为 page.meta，主要字段包括 call_control_id、call_duration、call_leg_id、call_session_id、client_state、record_type。

列出 Call Control 应用

使用 client.call_control_applications.list()（GET /call_control_applications）。响应包装中 items 为 page.data，pagination 为 page.meta，主要字段包括 id、created_at、updated_at、active、anchorsite_override、application_name。

其他 Call Control 应用操作

创建：client.call_control_applications.create()（POST /call_control_applications），必填 application_name、webhook_event_url
检索：client.call_control_applications.retrieve()（GET /call_control_applications/{id}），必填 id
更新：client.call_control_applications.update()（PATCH /call_control_applications/{id}），必填 application_name、webhook_event_url、id
删除：client.call_control_applications.delete()（DELETE /call_control_applications/{id}），必填 id
SIP Refer：client.calls.actions.refer()（POST /calls/{call_control_id}/actions/refer），必填 sip_address、call_control_id
发送 SIP Info：client.calls.actions.send_sip_info()（POST /calls/{call_control_id}/actions/send_sip_info），必填 content_type、body、call_control_id

Webhook 验证

Telnyx 使用 Ed25519 对 Webhook 进行签名，每个请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 请求头。生产环境必须验证签名：

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    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
    print(f"Received event: {event.data.event_type}")
    return "OK", 200

主要 Webhook 事件

call.answered：通话已接听，payload 包含 call_control_id、connection_id、call_leg_id、call_session_id 等
call.hangup：通话挂断，payload 字段同上
call.initiated：通话已发起，payload 额外包含 connection_codecs、offered_codecs
call.bridged：通话已桥接

使用方式与限制

Call Control 是事件驱动的。在 dial() 或收到入站 Webhook 后，后续命令需从 Webhook 处理器中基于事件 payload 中的 call_control_id 发起。外呼和入站流程不同：外呼从 dial() 开始，而入站呼叫必须先通过传入的 Webhook 接听，才能执行其他命令。实际呼叫控制需要一个公网可访问的 Webhook 端点，否则呼叫可能接通但应用无法驱动实时通话状态。

电话号码必须采用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。

错误处理：所有 API 调用可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。常见错误码包括 401 无效 API 密钥、403 权限不足、404 资源未找到、422 验证错误、429 速率限制（使用指数退避重试）。分页方面，列表方法返回自动分页迭代器，可用 for item in page_result 遍历所有页面。

适用场景

该技能适用于需要将语音通话能力集成到 Python 应用中的场景，例如呼叫中心、自动外呼系统、交互式语音应答（IVR）、通话转移与桥接、DTMF 采集以及音频流处理等。