Telnyx Numbers Services - Python 是一份基于 telnyx Python SDK 的能力说明文档，目标是帮助开发者通过 Python 代码配置电话号码相关的语音通道、紧急服务（E911）与语音信箱。文档中的全部示例都假设已经完成客户端初始化。
【安装与初始化】 安装命令为 pip install telnyx。初始化时需要从环境变量读取 API Key：import os，from telnyx import Telnyx，client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))。文档说明该 api_key 参数为默认值，可以省略。后续所有示例均假定 client 已按此方式初始化。
【错误处理】 文档强调所有 API 调用都可能失败，包括网络错误、限流（429）、校验错误（422）和认证错误（401），生产代码中应始终处理错误。示例分别捕获 telnyx.APIConnectionError（网络错误，建议检查连接并重试）、telnyx.RateLimitError（429 限流，建议等待后以指数退避重试，并检查 Retry-After 响应头确认实际等待时间）以及 telnyx.APIStatusError（可读取 status_code 与 message，其中 422 表示校验错误，应检查必填字段与格式）。文档列出的常见错误码含义为：401 表示 API Key 无效，403 表示权限不足，404 表示资源未找到，422 表示校验错误（检查字段格式），429 表示被限流（以指数退避重试）。
【使用方式与分页说明】 文档提示列表方法返回自动分页的迭代器，可使用 for item in page_result: 的方式自动遍历所有页。
【语音通道：非美国区域】 可以列出账户的非美国区域语音通道，返回内容包括 channels（int64）、countries（字符串数组）、created_at、id、name、record_type（枚举 channel_zone）以及 updated_at。支持的调用为 client.channel_zones.list()。更新非美国区域语音通道数量使用 PUT /channel_zones/{channel_zone_id}，channels 为必填参数，文档示例将 channels 设为 0。文档说明该能力用于让账户能够处理对非美国号码的多个并发入站呼叫，可根据预期呼叫量增减容量。
【语音通道：美国区域】 可以列出美国区域语音通道，返回 channels（整数）与 record_type。更新美国区域语音通道数量使用 PATCH /inbound_channels，channels 为必填参数，文档示例将 channels 设为 7。文档说明该能力用于让账户能够处理对美国号码的多个并发入站呼叫，可根据预期呼叫量增减容量。
【使用 Channel Billing 的号码查询】 可以检索所有使用 Channel Billing 的电话号码，并按 Zone 分组，调用方式为 client.list.retrieve_all()，返回 number_of_channels（整数）、numbers（对象数组）、zone_id 与 zone_name。也可查询指定 Zone 下使用 Channel Billing 的电话号码，调用方式为 client.list.retrieve_by_zone("channel_zone_id")，返回字段相同。
【动态紧急地址（E911）】 支持列出动态紧急地址（GET /dynamic_emergency_addresses），返回字段包括 administrative_area、country_code（枚举 US、CA、PR）、created_at、extended_address、house_number、house_suffix、id、locality、postal_code、record_type、sip_geolocation_id、status（枚举 pending、activated、rejected）、street_name、street_post_directional、street_pre_directional、street_suffix、updated_at。 创建动态紧急地址使用 POST /dynamic_emergency_addresses，必填字段为 house_number、street_name、locality、administrative_area、postal_code、country_code；可选字段包括 created_at、extended_address、house_suffix、id、record_type、sip_geolocation_id、status、street_post_directional、street_pre_directional、street_suffix、updated_at。文档示例使用 administrative_area="TX"、country_code="US"、house_number="600"、locality="Austin"、postal_code="78701"、street_name="Congress"。 获取单个动态紧急地址使用 GET /dynamic_emergency_addresses/{id}，删除使用 DELETE /dynamic_emergency_addresses/{id}，两者返回字段与上述一致。
【动态紧急端点（E911）】 支持列出动态紧急端点（GET /dynamic_emergency_endpoints），返回字段包括 callback_number、caller_name、created_at、dynamic_emergency_address_id、id、record_type、sip_from_id、status（枚举 pending、activated、rejected）、updated_at。 创建动态紧急端点使用 POST /dynamic_emergency_endpoints，必填字段为 dynamic_emergency_address_id、callback_number、caller_name；可选字段包括 created_at、id、record_type、sip_from_id、status、updated_at。文档示例使用 callback_number="+13125550000"、caller_name="Jane Doe Desk Phone"、dynamic_emergency_address_id="0ccc7b54-4df3-4bca-a65a-3da1ecc777f0"。 获取单个动态紧急端点使用 GET /dynamic_emergency_endpoints/{id}，删除使用 DELETE /dynamic_emergency_endpoints/{id}，两者返回字段与列表一致。
【语音信箱（Voicemail）】 可以获取某个电话号码的语音信箱设置，使用 GET /phone_numbers/{phone_number_id}/voicemail，返回 enabled（布尔值）与 pin（字符串）。文档示例传入 phone_number_id="123455678900"。 创建语音信箱设置使用 POST /phone_numbers/{phone_number_id}/voicemail，可选字段为 enabled（布尔值）与 pin（字符串），文档示例仅传入 phone_number_id，返回字段为 enabled 与 pin。 更新语音信箱设置使用 PATCH /phone_numbers/{phone_number_id}/voicemail，可选字段同样为 enabled 与 pin，返回 enabled 与 pin。
【适用场景与限制】 该文档适合需要使用 Python 管理 Telnyx 电话号码语音通道容量、动态紧急地址与端点、以及语音信箱设置的开发者。文档未提供价格、收费方式、其他语言 SDK、速率上限的具体数值或完整业务规则等信息，这些内容暂未提供。文中关于 Channel Billing 的完整说明与示例指向 Telnyx 支持文章，具体细节暂未提供。