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

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

Or set environment variables:

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

2. Make Your First Call

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

3. Set Up Inbound Call Handling

./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:

# 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:

# 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):

# 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:

# 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:

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

Conference Calls

Set up multi-party conference calls:

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

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

Call Recording & Transcription

# 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:

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

Integration Patterns

1. Appointment Reminders

#!/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

#!/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

#!/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:

./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 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

# 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

# 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

# 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