What this skill does

# 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