Agentic Calling

# Agentic Calling Skill

**使 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 # Simple call with message ./scripts/make-call.sh --to "+15551234567" --message "Hello from your AI assistant"

# Call with custom voice ./scripts/make-call.sh --to "+15551234567" --message "Important update" --voice "Polly.Matthew"

# Call with recording ./scripts/make-call.sh --to "+15551234567" --message "Please hold" --record true

# Call with status callback ./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 # Start webhook server on port 3000 ./scripts/receive-call.sh --port 3000

# Custom greeting ./scripts/receive-call.sh --port 3000 --greeting "Thank you for calling AI Services"

# Forward to another number ./scripts/receive-call.sh --port 3000 --forward "+15559876543"

# Record voicemail ./scripts/receive-call.sh --port 3000 --voicemail true ```

### `sms-notify.sh` - 发送 SMS 通知

发送短信消息（适用于电话跟进）：

```bash # Simple SMS ./scripts/sms-notify.sh --to "+15551234567" --message "Missed call from AI assistant"

# With media (MMS) ./scripts/sms-notify.sh --to "+15551234567" --message "Summary attached" --media "https://example.com/summary.pdf" ```

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

监控活动和已完成的通话：

```bash # Get status of specific call ./scripts/call-status.sh --sid "CA1234567890abcdef"

# List recent calls ./scripts/call-status.sh --list --limit 10

# Get call recording ./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 # Create conference ./scripts/conference.sh --create --name "Team Standup"

# Add participant ./scripts/conference.sh --add-participant --conference "Team Standup" --number "+15551234567" ```

### 通话录音与转录

```bash # Record and transcribe ./scripts/make-call.sh --to "+15551234567" --message "How can I help?" --record true --transcribe true

# Download recording ./scripts/call-status.sh --sid "CA123..." --download-recording --output "call.mp3"

# Get transcription ./scripts/call-status.sh --sid "CA123..." --get-transcript ```

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

使用 ElevenLabs 集成实现自定义语音：

```bash # Requires ElevenLabs API key ./scripts/make-call-elevenlabs.sh --to "+15551234567" --message "Hello" --voice-id "YOUR_VOICE_ID" ```

## 集成模式

### 1. 预约提醒

```bash #!/bin/bash # Send appointment reminder calls 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 # Broadcast emergency alert to list 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 # Call leads and route based on IVR response ./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`

## Webhooks 与 TwiML

### 设置 Webhooks

配置您的 Twilio 号码，在电话呼入时 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 # Check number formatting (must be E.164) ./scripts/validate-number.sh "+15551234567"

# Test connectivity ./scripts/make-call.sh --to "$TWILIO_PHONE_NUMBER" --message "Test call" ```

### Webhook 未接收到电话

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

# Check Twilio debugger ./scripts/check-logs.sh --recent 10 ```

### 音频质量问题

```bash # Use different voice engine ./scripts/make-call.sh --to "+15551234567" --message "Test" --voice "Google.en-US-Neural2-A"

# Adjust speech rate ./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` - 基于语音的 2FA

## API 参考

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

## 支持

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

## 许可证

MIT 许可证 - 欢迎在您自己的项目中使用

## 致谢

由 Kelly Claude（AI 助手）创建 由 Twilio 和 Clawdbot 提供支持