twilio-python

文档

Twilio API的文档可以在这里找到。

Python库文档可以在这里找到。

版本

twilio-python使用语义化版本控制的修改版本来进行所有更改。查看此文档了解详情。

支持的Python版本

该库支持以下Python实现：

• Python 3.7
• Python 3.8
• Python 3.9
• Python 3.10
• Python 3.11

安装

使用pip（Python的包管理器）从PyPi安装。

pip3 install twilio

如果在Windows上pip安装失败，请检查目录的路径长度。如果超过260个字符，请启用长路径或选择其他较短的位置。

没有安装pip？尝试通过在命令行运行以下命令来安装它：

curl https://bootstrap.pypa.io/get-pip.py | python

或者，你可以下载源代码(ZIP)，然后运行：

python3 setup.py install

提示 如果命令行给你一个权限拒绝的错误消息，尝试使用sudo运行上述命令（例如，sudo pip3 install twilio）。

测试你的安装

尝试给自己发送一条短信。将以下代码示例保存到你的电脑上的文本编辑器中。确保用你的Twilio账户中的值更新account_sid、auth_token和from_电话号码。to电话号码将是你自己的手机号码。

from twilio.rest import Client

# 你的账户SID和认证令牌，来自console.twilio.com
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)

将文件保存为send_sms.py。在终端中，cd到包含你刚保存的文件的目录，然后运行：

python3 send_sms.py

稍作延迟后，你将在手机上收到短信。

警告 在本地测试时硬编码你的凭证是可以的，但在提交任何代码或部署到生产环境之前，你应该使用环境变量来保密。查看如何设置环境变量以获取更多信息。

使用辅助库

API凭证

Twilio客户端需要你的Twilio凭证。你可以直接将这些凭证传递给构造函数（见下面的代码）或通过环境变量传递。

使用账户SID和认证令牌进行身份验证：

from twilio.rest import Client

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

使用API密钥和API密钥进行身份验证：

from twilio.rest import Client

api_key = "XXXXXXXXXXXXXXXXX"
api_secret = "YYYYYYYYYYYYYYYYYY"
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
client = Client(api_key, api_secret, account_sid)

或者，不带这些参数的Client构造函数将在当前环境中查找TWILIO_ACCOUNT_SID和TWILIO_AUTH_TOKEN变量。

我们建议将你的凭证存储为环境变量。为什么？你永远不用担心不小心提交你的凭证并将它们发布到某个公共场所。

from twilio.rest import Client
client = Client()

指定地区和/或边缘

要利用Twilio的全球基础设施，为客户端指定目标地区和/或边缘：

from twilio.rest import Client

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

不带这些参数的Client构造函数也会在当前环境中查找TWILIO_REGION和TWILIO_EDGE变量。

另外，你也可以在构造Twilio客户端后指定边缘和/或地区：

from twilio.rest import Client
client = Client()
client.region = 'au1'
client.edge = 'sydney'

这将导致hostname从api.twilio.com转变为api.sydney.au1.twilio.com。

拨打电话

from twilio.rest import Client

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

call = client.calls.create(to="9991231234",
                           from_="9991231234",
                           url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
print(call.sid)

获取现有通话的数据

from twilio.rest import Client

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

call = client.calls.get("CA42ed11f93dc08b952027ffbc406d0868")
print(call.to)

遍历记录

库会自动为您处理分页。集合，如calls和messages，有list和stream方法，这些方法在底层进行分页。使用list和stream时，您可以指定要接收的记录数量（limit）和每次获取页面的最大大小（page_size）。然后库会为您处理这个任务。

list方法会急切地获取所有记录并将它们作为列表返回，而stream方法返回一个迭代器，在您遍历集合时懒加载记录页面。您也可以使用page方法手动分页。

使用list方法

from twilio.rest import Client

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

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

异步API请求

默认情况下，Twilio客户端会向Twilio API发送同步请求。为了允许异步、非阻塞请求，我们包含了一个可选的异步HTTP客户端。当与客户端和相应的*_async方法一起使用时，对Twilio API的请求将异步执行。

from twilio.http.async_http_client import AsyncTwilioHttpClient
from twilio.rest import Client

async def main():
    account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    auth_token  = "your_auth_token"
    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!")

asyncio.run(main())

启用调试日志

将API请求和响应数据记录到控制台：

import logging

client = Client(account_sid, auth_token)
logging.basicConfig()
client.http_client.logger.setLevel(logging.INFO)

将API请求和响应数据记录到文件：

import logging

client = Client(account_sid, auth_token)
logging.basicConfig(filename='./log.txt')
client.http_client.logger.setLevel(logging.INFO)

处理异常

twilio-python的8.x版本导出了一个异常类，以帮助您处理特定于Twilio方法的异常。要使用它，请导入TwilioRestException并按如下方式捕获异常：

from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException

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

try:
  message = client.messages.create(to="+12316851234", from_="+15555555555",
                                   body="Hello there!")
except TwilioRestException as e:
  print(e)

生成TwiML

要控制电话呼叫，您的应用程序需要输出TwiML。

使用twilio.twiml.Response可以轻松创建这样的响应。

from twilio.twiml.voice_response import VoiceResponse

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

<?xml version="1.0" encoding="utf-8"?>
<Response><Say>Welcome to twilio!</Say></Response>

其他高级示例

• 了解如何创建自己的自定义HTTP客户端

Docker镜像

本仓库中的Dockerfile及其相应的twilio/twilio-python Docker镜像目前仅供Twilio用于测试目的。

获取帮助

如果您在安装或使用库时需要帮助，请先查看Twilio支持帮助中心，如果您没有找到问题的答案，请提交支持票据。

如果您发现库中的错误或想要添加新功能，请随时对此仓库开启issue或提交pull request！