介绍
# Twilio
通过托管的 OAuth 身份验证访问 Twilio API。发送短信、拨打电话、管理电话号码以及使用 Twilio 资源。
## 快速开始
```bash # List all accounts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/twilio/2010-04-01/Accounts.json') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/twilio/2010-04-01/Accounts/{AccountSid}/{resource}.json ```
网关将请求代理到 `api.twilio.com` 并自动注入您的 OAuth 令牌。
**重要提示：** 大多数 Twilio 端点要求路径中包含您的 Account SID。您可以从 `/Accounts.json` 端点获取您的 Account SID。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 访问 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Twilio OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=twilio&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'twilio'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "ebe566b1-3eaf-4926-bc92-0d8d47445f12", "status": "ACTIVE", "creation_time": "2026-02-09T23:18:44.243582Z", "last_updated_time": "2026-02-09T23:19:55.176687Z", "url": "https://connect.maton.ai/?session_token=...", "app": "twilio", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Twilio 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/twilio/2010-04-01/Accounts.json') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'ebe566b1-3eaf-4926-bc92-0d8d47445f12') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活跃连接。
## API 参考
### 账户
#### 列出账户
```bash GET /twilio/2010-04-01/Accounts.json ```
**响应：** ```json { "accounts": [ { "sid": "ACf5d980cd4b3f7604a464afaec191fc60", "friendly_name": "My first Twilio account", "status": "active", "date_created": "Mon, 09 Feb 2026 20:19:55 +0000", "date_updated": "Mon, 09 Feb 2026 20:20:05 +0000" } ] } ```
#### 获取账户
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}.json ```
### 消息
#### 列出消息
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Messages.json ```
**查询参数：** - `PageSize` - 每页结果数（默认：50） - `To` - 按收件人电话号码筛选 - `From` - 按发件人电话号码筛选 - `DateSent` - 按发送日期筛选
**响应：** ```json { "messages": [ { "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "body": "Hello!", "from": "+15551234567", "to": "+15559876543", "status": "delivered", "date_sent": "Mon, 09 Feb 2026 21:00:00 +0000" } ], "page": 0, "page_size": 50 } ```
#### 获取消息
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json ```
#### 发送消息
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Messages.json Content-Type: application/x-www-form-urlencoded
To=+15559876543&From=+15551234567&Body=Hello%20from%20Twilio! ```
**必需参数：** - `To` - 收件人电话号码（E.164 格式） - `From` - Twilio 电话号码或消息服务 SID - `Body` - 消息文本（最多 1600 个字符）
**可选参数：** - `MessagingServiceSid` - 使用它代替 From 进行消息路由 - `MediaUrl` - 要发送的媒体 URL (MMS) - `StatusCallback` - 用于状态更新的 Webhook URL
**响应：** ```json { "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "body": "Hello from Twilio!", "from": "+15551234567", "to": "+15559876543", "status": "queued", "date_created": "Mon, 09 Feb 2026 21:00:00 +0000" } ```
#### 更新消息（编辑）
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json Content-Type: application/x-www-form-urlencoded
Body= ```
将 Body 设置为空字符串将编辑掉消息内容。
#### 删除消息
```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json ```
成功时返回 204 No Content。
### 通话
#### 列出通话
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Calls.json ```
**查询参数：** - `PageSize` - 每页结果数 - `Status` - 按状态筛选（queued, ringing, in-progress, completed 等） - `To` - 按收件人筛选 - `From` - 按主叫人筛选
**响应：** ```json { "calls": [ { "sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "from": "+15551234567", "to": "+15559876543", "status": "completed", "duration": "60", "direction": "outbound-api" } ], "page": 0, "page_size": 50 } ```
#### 获取通话
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json ```
#### 拨打电话
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Calls.json Content-Type: application/x-www-form-urlencoded
To=+15559876543&From=+15551234567&Url=https://example.com/twiml ```
**必需参数：** - `To` - 收件人电话号码 - `From` - Twilio 电话号码 - `Url` - TwiML 应用程序 URL
**可选参数：** - `StatusCallback` - 用于通话状态更新的 Webhook URL - `StatusCallbackEvent` - 要接收的事件（initiated, ringing, answered, completed） - `Timeout` - 等待接听的秒数（默认：60） - `Record` - 设置为 true 以录制通话
#### 更新通话
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json Content-Type: application/x-www-form-urlencoded
Status=completed ```
使用 `Status=completed` 结束正在进行的通话。
#### 删除通话
```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json ```
### 电话号码
#### 列出呼入电话号码
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json ```
**响应：** ```json { "incoming_phone_numbers": [ { "sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "phone_number": "+15551234567", "friendly_name": "My Number", "capabilities": { "voice": true, "sms": true, "mms": true } } ] } ```
#### 获取电话号码
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json ```
#### 更新电话号码
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json Content-Type: application/x-www-form-urlencoded
FriendlyName=Updated%20Name&VoiceUrl=https://example.com/voice ```
#### 删除电话号码
```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json ```
### 应用程序
#### 列出应用程序
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Applications.json ```
**响应：** ```json { "applications": [ { "sid": "APxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My App", "voice_url": "https://example.com/voice", "sms_url": "https://example.com/sms" } ] } ```
#### 获取应用程序
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Applications/{ApplicationSid}.json ```
#### 创建应用程序
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Applications.json Content-Type: application/x-www-form-urlencoded
FriendlyName=My%20App&VoiceUrl=https://example.com/voice ```
**响应：** ```json { "sid": "APxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My App", "voice_url": "https://example.com/voice", "date_created": "Tue, 10 Feb 2026 00:20:15 +0000" } ```
#### 更新应用程序
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Applications/{ApplicationSid}.json Content-Type: application/x-www-form-urlencoded
FriendlyName=Updated%20App%20Name ```
#### 删除应用程序
```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Applications/{ApplicationSid}.json ```
成功时返回 204 No Content。
### 队列
#### 列出队列
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Queues.json ```
**响应：** ```json { "queues": [ { "sid": "QUxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "Support Queue", "current_size": 0, "max_size": 1000, "average_wait_time": 0 } ] } ```
#### 创建队列
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Queues.json Content-Type: application/x-www-form-urlencoded
FriendlyName=Support%20Queue&MaxSize=100 ```
#### 更新队列
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Queues/{QueueSid}.json Content-Type: application/x-www-form-urlencoded
FriendlyName=Updated%20Queue%20Name ```
#### 删除队列
```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Queues/{QueueSid}.json ```
### 地址
#### 列出地址
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Addresses.json ```
#### 创建地址
```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Addresses.json Content-Type: application/x-www-form-urlencoded
FriendlyName=Office&Street=123%20Main%20St&City=San%20Francisco&Region=CA&PostalCode=94105&IsoCountry=US&CustomerName=Acme%20Inc ```
### 使用记录
#### 列出使用记录
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Usage/Records.json ```
**查询参数：** - `Category` - 按使用类别筛选（calls, sms 等） - `StartDate` - 开始日期 (YYYY-MM-DD) - `EndDate` - 结束日期 (YYYY-MM-DD)
**响应：** ```json { "usage_records": [ { "category": "sms", "description": "SMS Messages", "count": "100", "price": "0.75", "start_date": "2026-02-01", "end_date": "2026-02-28" } ] } ```
## 分页
Twilio 使用基于页面的分页：
```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Messages.json?PageSize=50&Page=0 ```
**参数：** - `PageSize` - 每页结果数（默认：50） - `Page` - 页码（从 0 开始索引）
**响应包括：** ```json { "messages": [...], "page": 0, "page_size": 50, "first_page_uri": "/2010-04-01/Accounts/{AccountSid}/Messages.json?PageSize=50&Page=0", "next_page_uri": "/2010-04-01/Accounts/{AccountSid}/Messages.json?PageSize=50&Page=1", "previous_page_uri": null } ```
使用 `next_page_uri` 获取下一页结果。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/twilio/2010-04-01/Accounts.json', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); const accountSid = data.accounts[0].sid; console.log(`Account SID: ${accountSid}`); ```
### Python
```python import os import requests
# Get account SID response = requests.get( 'https://gateway.maton.ai/twilio/2010-04-01/Accounts.json', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) account_sid = response.json()['accounts'][0]['sid'] print(f"Account SID: {account_sid}") ```
### Python (发送短信)
```python import os import requests
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
response = requests.post( f'https://gateway.maton.ai/twilio/2010-04-01/Accounts/{account_sid}/Messages.json', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/x-www-form-urlencoded' }, data={ 'To': '+15559876543', 'From': '+15551234567', 'Body': 'Hello from Python!' } ) message = response.json() print(f"Message SID: {message['sid']}") print(f"Status: {message['status']}") ```
### Python (拨打电话)
```python import os import requests
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
response = requests.post( f'https://gateway.maton.ai/twilio/2010-04-01/Accounts/{account_sid}/Calls.json', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/x-www-form-urlencoded' }, data={ 'To': '+15559876543', 'From': '+15551234567', 'Url': 'https://demo.twilio.com/docs/voice.xml' } ) call = response.json() print(f"Call SID: {call['sid']}") print(f"Status: {call['status']}") ```
## 注意事项
- 所有端点都需要 `/2010-04-01/` API 版本前缀 - 大多数端点要求路径中包含您的 Account SID - 请求正文使用 `application/x-www-form-urlencoded` 格式（而非 JSON） - 电话号码必须采用 E.164 格式 (+15551234567) - SID 是唯一标识符： - 账户 SID 以 `AC` 开头 - 消息 SID 以 `SM` (SMS) 或 `MM` (MMS) 开头 - 通话 SID 以 `CA` 开头 - 电话号码 SID 以 `PN` 开头 - 应用程序 SID 以 `AP` 开头 - 队列 SID 以 `QU` 开头 - POST 用于创建和更新资源 - DELETE 成功时返回 204 No Content - 重要提示：当将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Twilio 连接或请求错误 | | 401 | 无效或缺少 Maton API 密钥 | | 404 | 未找到资源 | | 429 | 速率受限 | | 4xx/5xx | 来自 Twilio API 的透传错误 |
Twilio 错误响应包括： ```json { "code": 20404, "message": "The requested resource was not found", "more_info": "https://www.twilio.com/docs/errors/20404", "status": 404 } ```
### 故障排除：无效的 API 密钥
**当您收到“无效的 API 密钥”错误时，在断定存在问题之前，请务必执行以下步骤：**
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 资源
- [Twilio API 概述](https://www.twilio.com/docs/usage/api) - [消息 API](https://www.twilio.com/docs/messaging/api/message-resource) - [通话 API](https://www.twilio.com/docs/voice/api/call-resource) - [电话号码 API](https://www.twilio.com/docs/phone-numbers/api/incomingphonenumber-resource) - [应用程序 API](https://www.twilio.com/docs/usage/api/applications) - [使用记录 API](https://www.twilio.com/docs/usage/api/usage-record)