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:

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:

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

English (UK):

Other Languages:

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

    Hello! Thank you for calling.
    
        Press 1 for sales, 2 for support, or 3 to leave a message.
    

Cost Optimization

Tips:

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:

API Reference

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

Support

License

MIT License - feel free to use in your own projects

Credits

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

See examples/ directory for complete use cases:

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

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