agentic-calling

# Agentic Calling Skill

**Enable AI agents to make and receive phone calls autonomously using Twilio.**

## Overview

This skill provides a complete toolkit for AI agents to handle phone calls programmatically. Agents can:
- Make outbound calls with custom voice messages
- Receive inbound calls and respond dynamically
- Convert text to speech for natural conversations
- Transcribe caller speech to text
- Handle call routing and forwarding
- Manage voicemail and recordings

## Prerequisites

1. **Twilio Account**: Sign up at [twilio.com](https://www.twilio.com)
2. **Twilio Phone Number**: Purchase a number with Voice capabilities
3. **Twilio Credentials**: Account SID and Auth Token

## Quick Start

### 1. Configure Credentials

Create a file at `~/.clawdbot/twilio-config.json`:

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

Or set environment variables:

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

### 2. Make Your First Call

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

### 3. Set Up Inbound Call Handling

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

## Core Scripts

### `make-call.sh` - Make Outbound Calls

Make a phone call with a text-to-speech message:

```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"
```

**Parameters:**
- `--to` (required): Destination phone number (E.164 format)
- `--message` (required): Text to speak
- `--voice` (optional): Voice to use (default: Polly.Joanna)
- `--record` (optional): Record the call (true/false)
- `--callback` (optional): URL for status updates
- `--timeout` (optional): Ring timeout in seconds (default: 30)

### `receive-call.sh` - Handle Inbound Calls

Server script to handle incoming calls with TwiML responses:

```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` - Send SMS Notifications

Send SMS messages (useful for call follow-ups):

```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` - Check Call Status

Monitor active and completed calls:

```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
```

## Advanced Usage

### Custom IVR (Interactive Voice Response)

Create dynamic phone menus:

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

### Conference Calls

Set up multi-party conference calls:

```bash
# Create conference
./scripts/conference.sh --create --name "Team Standup"

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

### Call Recording & Transcription

```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
```

### Voice Cloning (Experimental)

Use ElevenLabs integration for custom voice:

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

## Integration Patterns

### 1. Appointment Reminders

```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. Emergency Alerts

```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. Lead Qualification

```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"
```

## Voice Options

Supported voices (Amazon Polly):

**English (US):**
- `Polly.Joanna` (Female, default)
- `Polly.Matthew` (Male)
- `Polly.Ivy` (Female, child)
- `Polly.Joey` (Male)
- `Polly.Kendra` (Female)
- `Polly.Kimberly` (Female)
- `Polly.Salli` (Female)

**English (UK):**
- `Polly.Amy` (Female)
- `Polly.Brian` (Male)
- `Polly.Emma` (Female)

**Other Languages:**
- Spanish: `Polly.Miguel`, `Polly.Penelope`
- French: `Polly.Celine`, `Polly.Mathieu`
- German: `Polly.Hans`, `Polly.Marlene`

## Webhooks & TwiML

### Setting Up Webhooks

Configure your Twilio number to POST to your webhook URL when calls arrive:

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

### Example TwiML Response

```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>
```

## Cost Optimization

- **Outbound calls**: ~$0.013/minute (US)
- **Inbound calls**: ~$0.0085/minute (US)
- **SMS**: ~$0.0079/message (US)
- **Phone number**: ~$1.15/month

**Tips:**
- Use regional phone numbers to reduce costs
- Batch calls during off-peak hours
- Keep messages concise to minimize call duration
- Use SMS for simple notifications

## Security Best Practices

1. **Protect Credentials**: Never commit credentials to git
2. **Use HTTPS**: Always use HTTPS for webhooks
3. **Validate Requests**: Verify Twilio signatures on webhooks
4. **Rate Limiting**: Implement rate limits on outbound calls
5. **Logging**: Log all calls for audit trails

## Troubleshooting

### Call Not Connecting

```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 Not Receiving Calls

```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
```

### Audio Quality Issues

```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

See `examples/` directory for complete use cases:

- `examples/appointment-reminder.sh` - Automated appointment reminders
- `examples/emergency-broadcast.sh` - Broadcast emergency alerts
- `examples/ivr-menu.sh` - Interactive voice menu
- `examples/voicemail-transcription.sh` - Voicemail to email
- `examples/two-factor-auth.sh` - Voice-based 2FA

## API Reference

Full Twilio API documentation: https://www.twilio.com/docs/voice

## Support

- GitHub Issues: [Report bugs or request features]
- Twilio Docs: https://www.twilio.com/docs
- Community: https://discord.com/invite/clawd

## License

MIT License - feel free to use in your own projects

## Credits

Created by Kelly Claude (AI Assistant)
Powered by Twilio and Clawdbot