agent-call

AI-powered outbound calling service. Use when user expresses intent to make phone calls (e.g., "help me call xxx to book a table", "call customer about promo...

Security Scan

The package implements Twilio-based calling scripts that match the described purpose, but there are multiple metadata, declaration, and documentation inconsistencies (missing declared env requirements, missing referenced scripts, mismatched metadata) that warrant caution before installing or providing credentials.

Purpose & Capability

The skill's stated purpose (Twilio outbound/inbound calling) matches the included scripts (make-call.sh, call-status.sh, sms-notify.sh). However, the registry metadata claimed no required environment variables or primary credential while the SKILL.md and scripts clearly require Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER) or a config file at ~/.clawdbot/twilio-config.json. skill.json declares a 'requires.twilio_account' field and dependencies (jq, curl, python3) but those required env vars were not reflected in the top-level registry requirements — an incoherence that can mislead users about what secrets the skill needs.

Instruction Scope

The runtime instructions and scripts stay within the telephony domain (calling Twilio APIs, building TwiML, handling recordings/transcriptions). They ask the agent/user to create a local config file or set env vars and to provide optional callback URLs. However SKILL.md references several scripts and features (receive-call.sh, setup-webhook.sh, create-ivr.sh, conference.sh, make-call-elevenlabs.sh) that are not present in the file manifest, creating a mismatch between documented capabilities and shipped files.

Install Mechanism

There is no network install step or downloader; this is an instruction/script-only skill packaged with shell scripts. No external archives or unknown URLs are fetched at install time. Required external tools (curl, jq, python3) are declared in skill.json and are appropriate for the task.

Credentials

The actual scripts require Twilio account credentials (Account SID and Auth Token) and a Twilio phone number to operate — these are sensitive secrets. The skill metadata/registry omitted listing these required environment variables and did not declare the primary credential, which is disproportionate to how credentials should be presented to users. SKILL.md also mentions an optional ElevenLabs API key for voice cloning but this credential is not declared anywhere in registry metadata. Asking for telephony credentials is reasonable for the stated function, but the omission in the declared requirements is a red flag for transparency.

Persistence & Privilege

The skill is not configured with always:true and doesn't request any system-wide configuration changes. The scripts operate only on a per-user config file (~/.clawdbot/twilio-config.json) or environment variables and do not attempt to modify other skills or agent settings. Autonomous invocation is allowed by default on the platform but not an additional privilege requested by the skill.

What to consider before installing

This skill appears to implement Twilio-based calling and includes working scripts, but there are several red flags you should act on before installing or providing credentials: - Do not supply your primary Twilio Account SID/Auth Token until you verify the code origin. The package metadata omitted declaring required env vars even though the scripts use them. - Verify missing files: SKILL.md documents webhook/receive/IVR/conference scripts that are not present in the manifest. Ask the publisher or inspect a canonical source (repo/homepage) to ensure you have the full implementation. - Use a sandbox/test Twilio account and a disposable phone number when you first try it to limit potential costs and exposure. - Inspect the scripts yourself (they are bash and plain-text) to confirm there is no hidden network exfiltration or unexpected callbacks. In particular, review any code that would run webhook setup or callback handling for URLs you don't control. - If you must run it, run in an isolated environment (container or VM), do not grant real production credentials, and restrict callback URLs to endpoints you control and trust. - Prefer packages with a verifiable upstream repository/homepage and matching registry metadata (owner, slug, required envs). The source here is 'unknown' and the package metadata (ownerId/slug/version) doesn't consistently match file _meta.json and skill.json; treat that as a sign to verify provenance. If the publisher can supply a canonical repository and update the registry metadata to declare required credentials (and provide the missing scripts or remove undocumented features), re-evaluate; the current inconsistencies are the main reason this is flagged as suspicious.

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 "[phone]" --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 "[phone]" --message "Hello from your AI assistant"

# Call with custom voice
./scripts/make-call.sh --to "[phone]" --message "Important update" --voice "Polly.Matthew"

# Call with recording
./scripts/make-call.sh --to "[phone]" --message "Please hold" --record true

# Call with status callback
./scripts/make-call.sh --to "[phone]" --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 "[phone]"

# 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 "[phone]" --message "Missed call from AI assistant"

# With media (MMS)
./scripts/sms-notify.sh --to "[phone]" --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 "[phone]"

Call Recording & Transcription

# Record and transcribe
./scripts/make-call.sh --to "[phone]" --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 "[phone]" --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 "[phone]" \
  --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 "[phone]"

# 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=[phone]" \
  -d "From=[phone]"

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

Audio Quality Issues

# Use different voice engine
./scripts/make-call.sh --to "[phone]" --message "Test" --voice "Google.en-US-Neural2-A"

# Adjust speech rate
./scripts/make-call.sh --to "[phone]" --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