twilio-python：Python 接入 Twilio 的官方 SDK

twilio-python 在 GitHub 上已经拿到 2,060 个 Star 了。

这是 Twilio 官方维护的 Python SDK，用来对接 Twilio 的通信 API。短信、语音电话、通话记录查询、TwiML 生成，都能通过几行 Python 代码完成。

1、这库是干嘛的

一句话：用 Python 调用 Twilio 的通信服务。

Twilio 是云通信平台，提供短信、语音、视频等 API。twilio-python 把这些 API 封装成 Python 对象和方法，开发者不用自己拼 HTTP 请求，直接 import 就能用。

支持的功能包括：

• 发送和接收 SMS/MMS
• 拨打电话、管理通话
• 查询通话和消息记录
• 生成 TwiML 语音指令
• 异步非阻塞请求
• OAuth 2.0 认证（beta）

2、安装和基础用法

安装从 PyPI 拉：

pip3 install twilio

Python 3.7 到 3.13 都支持。

发一条短信只需要这几行：

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

message = client.messages.create(
    to="+15558675309",
    from_="+15017250604",
    body="Hello from Python!")

print(message.sid)

保存为 py 文件，命令行直接跑。手机几秒钟后就能收到短信。

3、认证方式

SDK 提供两种认证方式。

第一种，直接用 Account SID 和 Auth Token：

client = Client(account_sid, auth_token)

第二种，用 API Key 和 API Secret，权限粒度更细：

client = Client(api_key, api_secret, account_sid)

也可以不传参数，让 SDK 自动读取环境变量 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN：

client = Client()

生产环境建议用环境变量，避免把密钥写进代码仓库。

4、其他实用功能

拨打电话

call = client.calls.create(
    to="9991231234",
    from_="9991231234",
    url="http://twimlets.com/holdmusic")

print(call.sid)

分页自动处理

查询通话记录或消息列表时，SDK 自动处理分页。list() 一次性拉完，stream() 按需懒加载：

for sms in client.messages.list():
    print(sms.to)

也可以指定每次拉多少条、总共拉多少条：

client.messages.list(limit=20, page_size=10)

异步请求

默认同步请求，也可以切到异步模式：

from twilio.http.async_http_client import AsyncTwilioHttpClient

http_client = AsyncTwilioHttpClient()
client = Client(account_sid, auth_token, http_client=http_client)

message = await client.messages.create_async(
    to="+12316851234",
    from_="+15555555555",
    body="Hello there!")

全局基础设施

Twilio 有多个区域节点。SDK 支持指定 region 和 edge：

client = Client(region='au1', edge='sydney')

请求会路由到 api.sydney.au1.twilio.com。

生成 TwiML

TwiML 是 Twilio 的 XML 指令集，用来控制通话流程：

from twilio.twiml.voice_response import VoiceResponse

r = VoiceResponse()
r.say("Welcome to twilio!")
print(str(r))

输出的是标准 XML，Twilio 服务器会解析并执行对应的语音操作。

异常处理

SDK 导出了 TwilioRestException，可以精确捕获 Twilio 相关的 API 错误：

from twilio.base.exceptions import TwilioRestException

try:
    message = client.messages.create(...)
except TwilioRestException as e:
    print(e)

5、适合哪些人用

• 需要在 Python 项目里集成短信或语音通知的开发者
• 用 Twilio 做 OTP、告警推送、客服系统的团队
• 构建通信相关应用、需要程序化控制电话和短信的人

这个库文档完整，示例充足，官方持续维护。已经在生产环境跑了很多年，稳定性经过验证。

print(e)

## 5、适合哪些人用

- 需要在 Python 项目里集成短信或语音通知的开发者
- 用 Twilio 做 OTP、告警推送、客服系统的团队
- 构建通信相关应用、需要程序化控制电话和短信的人

这个库文档完整，示例充足，官方持续维护。已经在生产环境跑了很多年，稳定性经过验证。