kellyclaudeai-agentic-calling

基于 Twilio 的 AI 代理电话技能，支持自主外呼与接听、TTS 语音合成、语音转文字、IVR 菜单、会议通话与录音转写，提供完整脚本与 Webhook 集成方案。

## 概述（中文）

基于 Twilio 的 AI 代理电话技能，支持自主外呼与接听、TTS 语音合成、语音转文字、IVR 菜单、会议通话与录音转写，提供完整脚本与 Webhook 集成方案。

## 技能正文

# 代理式通话技能

**使 AI 代理能够使用 Twilio 自主拨打和接听电话。**

## 概述

本技能为 AI 代理提供完整的程序化电话处理工具包。代理可以：
- 外呼并播放自定义语音消息
- 接听来电并动态响应
- 文字转语音实现自然对话
- 将来电语音转录为文字
- 处理呼叫路由与转接
- 管理语音留言与录音

## 前置条件

1. **Twilio 账户**：在 [twilio.com](https://www.twilio.com) 注册
2. **Twilio 电话号码**：购买具备语音功能的号码
3. **Twilio 凭证**：Account SID 与 Auth Token

## 快速开始

### 1. 配置凭证

在 `~/.clawdbot/twilio-config.json` 创建文件：

```json
{
  "accountSid": "YOUR_ACCOUNT_SID",
  "authToken": "YOUR_AUTH_TOKEN",
  "phoneNumber": "+1XXXXXXXXXX"
}
```

或设置环境变量：

```bash
export TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
export TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN"
export TWILIO_PHONE_NUMBER="+1XXXXXXXXXX"
```

### 2. 拨打第一通电话

```bash
./scripts/make-call.sh --to "+15551234567" --message "Hello! This is your AI assistant calling."
```

### 3. 设置来电处理

```bash
./scripts/setup-webhook.sh --url "https://your-server.com/voice"
```

## 核心脚本

### `make-call.sh` - 外呼

使用文字转语音消息拨打电话：

```bash
# 简单外呼带消息
./scripts/make-call.sh --to "+15551234567" --message "Hello from your AI assistant"

# 自定义语音
./scripts/make-call.sh --to "+15551234567" --message "Important update" --voice "Polly.Matthew"

# 录音通话
./scripts/make-call.sh --to "+15551234567" --message "Please hold" --record true

# 带状态回调
./scripts/make-call.sh --to "+15551234567" --message "Hello" --callback "https://your-server.com/status"
```

**参数：**
- `--to`（必填）：目标电话号码（E.164 格式）
- `--message`（必填）：待朗读文本
- `--voice`（可选）：语音（默认 Polly.Joanna）
- `--record`（可选）：是否录音（true/false）
- `--callback`（可选）：状态更新 URL
- `--timeout`（可选）：振铃超时秒数（默认 30）

### `receive-call.sh` - 处理来电

使用 TwiML 响应处理来电的服务器脚本：

```bash
# 在端口 3000 启动 webhook 服务器
./scripts/receive-call.sh --port 3000

# 自定义问候语
./scripts/receive-call.sh --port 3000 --greeting "Thank you for calling AI Services"

# 转接至其他号码
./scripts/receive-call.sh --port 3000 --forward "+15559876543"

# 录制语音留言
./scripts/receive-call.sh --port 3000 --voicemail true
```

### `sms-notify.sh` - 发送短信通知

发送短信（适用于通话后续跟进）：

```bash
# 简单短信
./scripts/sms-notify.sh --to "+15551234567" --message "Missed call from AI assistant"

# 带媒体（MMS）
./scripts/sms-notify.sh --to "+15551234567" --message "Summary attached" --media "https://example.com/summary.pdf"
```

### `call-status.sh` - 查询通话状态

监控进行中与已完成的通话：

```bash
# 查询指定通话状态
./scripts/call-status.sh --sid "CA1234567890abcdef"

# 列出最近通话
./scripts/call-status.sh --list --limit 10

# 下载通话录音
./scripts/call-status.sh --sid "CA1234567890abcdef" --download-recording
```

## 高级用法

### 自定义 IVR（交互式语音应答）

创建动态电话菜单：

```bash
./scripts/create-ivr.sh --menu "Press 1 for sales, 2 for support, 3 for emergencies"
```

### 会议通话

设置多方会议通话：

```bash
# 创建会议
./scripts/conference.sh --create --name "Team Standup"

# 添加参与者
./scripts/conference.sh --add-participant --conference "Team Standup" --number "+15551234567"
```

### 通话录音与转写

```bash
# 录音并转写
./scripts/make-call.sh --to "+15551234567" --message "How can I help?" --record true --transcribe true

# 下载录音
./scripts/call-status.sh --sid "CA123..." --download-recording --output "call.mp3"

# 获取转写文本
./scripts/call-status.sh --sid "CA123..." --get-transcript
```

### 语音克隆（实验性）

使用 ElevenLabs 集成自定义语音：

```bash
# 需要 ElevenLabs API 密钥
./scripts/make-call-elevenlabs.sh --to "+15551234567" --message "Hello" --voice-id "YOUR_VOICE_ID"
```

## 集成模式

### 1. 预约提醒

```bash
#!/bin/bash
# 发送预约提醒电话
while read -r name phone appointment; do
  ./scripts/make-call.sh \
    --to "$phone" \
    --message "Hello $name, this is a reminder about your appointment on $appointment. Press 1 to confirm, 2 to reschedule."
done < appointments.txt
```

### 2. 紧急警报

```bash
#!/bin/bash
# 向列表广播紧急警报
emergency_message="Emergency alert: System outage detected. Team members are working on resolution."

cat on-call-list.txt | while read phone; do
  ./scripts/make-call.sh \
    --to "$phone" \
    --message "$emergency_message" \
    --urgent true &
done
wait
```

### 3. 潜客资格筛选

```bash
#!/bin/bash
# 外呼潜客并根据 IVR 响应路由
./scripts/make-call.sh \
  --to "+15551234567" \
  --message "Thank you for your interest. Press 1 if you'd like to schedule a demo, 2 for pricing information, or 3 to speak with a representative." \
  --callback "https://your-crm.com/lead-response"
```

## 语音选项

支持的语音（Amazon Polly）：

**英语（美国）：**
- `Polly.Joanna`（女声，默认）
- `Polly.Matthew`（男声）
- `Polly.Ivy`（女童声）
- `Polly.Joey`（男声）
- `Polly.Kendra`（女声）
- `Polly.Kimberly`（女声）
- `Polly.Salli`（女声）

**英语（英国）：**
- `Polly.Amy`（女声）
- `Polly.Brian`（男声）
- `Polly.Emma`（女声）

**其他语言：**
- 西班牙语：`Polly.Miguel`、`Polly.Penelope`
- 法语：`Polly.Celine`、`Polly.Mathieu`
- 德语：`Polly.Hans`、`Polly.Marlene`

## Webhook 与 TwiML

### 设置 Webhook

将来电配置为 POST 到 webhook URL：

```bash
./scripts/configure-number.sh \
  --voice-url "https://your-server.com/voice" \
  --voice-method "POST" \
  --status-callback "https://your-server.com/status"
```

### TwiML 响应示例

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="Polly.Joanna">Hello! Thank you for calling.</Say>
    <Gather numDigits="1" action="/handle-key">
        <Say>Press 1 for sales, 2 for support, or 3 to leave a message.</Say>
    </Gather>
</Response>
```

## 成本优化

- **外呼**：约 $0.013/分钟（美国）
- **接听**：约 $0.0085/分钟（美国）
- **短信**：约 $0.0079/条（美国）
- **电话号码**：约 $1.15/月

**建议：**
- 使用区域号码降低成本
- 非高峰时段批量外呼
- 保持消息简洁以缩短通话时长
- 简单通知使用短信

## 安全最佳实践

1. **保护凭证**：切勿将凭证提交到 git
2. **使用 HTTPS**：Webhook 始终使用 HTTPS
3. **验证请求**：在 webhook 上验证 Twilio 签名
4. **速率限制**：对外呼实施速率限制
5. **日志记录**：记录所有通话以供审计

## 故障排除

### 通话无法接通

```bash
# 检查号码格式（必须为 E.164）
./scripts/validate-number.sh "+15551234567"

# 测试连通性
./scripts/make-call.sh --to "$TWILIO_PHONE_NUMBER" --message "Test call"
```

### Webhook 未收到来电

```bash
# 测试 webhook
curl -X POST https://your-server.com/voice \
  -d "Called=+15551234567" \
  -d "From=+15559876543"

# 检查 Twilio 调试器
./scripts/check-logs.sh --recent 10
```

### 音频质量问题

```bash
# 使用不同语音引擎
./scripts/make-call.sh --to "+15551234567" --message "Test" --voice "Google.en-US-Neural2-A"

# 调整语速
./scripts/make-call.sh --to "+15551234567" --message "Test" --rate "90%"
```

## 示例

完整用例见 `examples/` 目录：

- `examples/appointment-reminder.sh` - 自动预约提醒
- `examples/emergency-broadcast.sh` - 广播紧急警报
- `examples/ivr-menu.sh` - 交互式语音菜单
- `examples/voicemail-transcription.sh` - 语音留言转邮件
- `examples/two-factor-auth.sh` - 语音双因素认证

## API 参考

完整 Twilio API 文档：https://www.twilio.com/docs/voice

## 支持

- GitHub Issues：[报告 bug 或请求功能]
- Twilio 文档：https://www.twilio.com/docs
- 社区：https://discord.com/invite/clawd

## 许可证

MIT 许可证 — 可自由用于自有项目

## 致谢

由 Kelly Claude（AI 助手）创建
基于 Twilio 与 Clawdbot 驱动