Dialpad Skill

Dialpad Skill

Send SMS and make voice calls via the Dialpad API.

Available Phone Numbers

Use --from <number> to specify which number appears as caller ID.

Setup

Required environment variable:

DIALPAD_API_KEY=your_api_key_here

Optional (for ElevenLabs TTS in calls):

ELEVENLABS_API_KEY=your_elevenlabs_api_key

Get your Dialpad API key from Dialpad API Settings.

Usage

Send SMS

# Basic SMS
python3 send_sms.py --to "+14155551234" --message "Hello from Clawdbot!"

# From specific number (e.g., work phone)
python3 send_sms.py --to "+14155551234" --message "Hello!" --from "+14153602954"

# Batch SMS (up to 10 recipients)
python3 send_sms.py --to "+14155551234" "+14155555678" --message "Group update"

Make Voice Calls

# Basic call (ring recipient - they'll answer to speak with you)
python3 make_call.py --to "+14155551234"

# Call with Text-to-Speech greeting (Dialpad's robotic TTS)
python3 make_call.py --to "+14155551234" --text "Hello! This is a call from ShapeScale."

# Call from specific number with TTS
python3 make_call.py --to "+14155551234" --from "+14153602954" --text "Meeting reminder"

# With custom voice (requires ELEVENLABS_API_KEY)
python3 make_call.py --to "+14155551234" --voice "Adam" --text "Premium voice test"

From Agent Instructions

SMS:

python3 send_sms.py --to "+14155551234" --message "Your message here"

Voice Call:

python3 make_call.py --to "+14155551234" --text "Optional TTS message"

Voice Options

Low-Cost Voices (Recommended for Budget)

Premium Voices (Higher Quality)

To use a specific voice, add --voice "VoiceName".

API Capabilities

SMS

• Endpoint: POST https://dialpad.com/​api/​v2/​sms
• Max recipients: 10 per request
• Max message length: 1600 characters
• Rate limits: 100-800 requests/​minute (tier-dependent)

Voice Calls

• Endpoint: POST https://dialpad.com/​api/​v2/​call
• Requires: phone_number + user_id
• Features: Outbound calling, Text-to-Speech
• Caller ID: Must be assigned to your Dialpad account

Known Users (Auto-Detected)

Response

SMS Response

{
  "id": "4612924117884928",
  "status": "pending",
  "message_delivery_result": "pending",
  "to_numbers": ["+14158235304"],
  "from_number": "+14155201316",
  "direction": "outbound"
}

Call Response

{
  "call_id": "6342343299702784",
  "status": "ringing"
}

Error Handling

SMS Storage (SQLite with FTS5)

Messages are stored in a single SQLite database with full-text search.

Storage

~/​.dialpad/​sms.db  # Single file with messages + FTS5 index

Commands

# List all SMS conversations
python3 sms_sqlite.py list

# View specific conversation thread
python3 sms_sqlite.py thread "+14155551234"

# Full-text search across all messages
python3 sms_sqlite.py search "demo"

# Show unread message summary
python3 sms_sqlite.py unread

# Statistics
python3 sms_sqlite.py stats

# Mark messages as read
python3 sms_sqlite.py read "+14155551234"

# Migrate from legacy storage
python3 sms_sqlite.py migrate

Features

• Full-text search via FTS5 (search "keyword")
• Fast queries with indexes on contact, timestamp, direction
• ACID transactions — no corruption on concurrent writes
• Unread tracking with per-contact counts
• Denormalized contact stats for instant list views

Webhook Integration

from webhook_sqlite import handle_sms_webhook, format_notification, get_inbox_summary

# Store incoming message
result = handle_sms_webhook(dialpad_payload)
notification = format_notification(result)

# Get inbox summary
summary = get_inbox_summary()

Legacy JSON Storage (Deprecated)

The original JSON-based storage is still available but not recommended:

python3 sms_storage.py [list|thread|search|unread]

Requirements

• Python 3.7+
• No external dependencies (uses stdlib only)
• Valid DIALPAD_API_KEY environment variable
• For ElevenLabs TTS: ELEVENLABS_API_KEY + webhook setup for audio playback

Reading SMS Messages

Dialpad doesn't provide a direct "GET /​sms" endpoint. Instead, use:

1. Real-Time: SMS Webhooks

Receive SMS events in real-time when messages are sent/​received.

# Create a webhook subscription
python3 create_sms_webhook.py create --url "https://your-server.com/​webhook/​dialpad" --direction "all"

# List existing subscriptions
python3 create_sms_webhook.py list

Webhook Events:

• sms_sent — Outgoing SMS
• sms_received — Incoming SMS

Note: Add message_content_export scope to receive message text in events.

2. Historical: Stats Export API

Export past SMS messages as CSV.

# Export all SMS
python3 export_sms.py --output all_sms.csv

# Export by date range
python3 export_sms.py --start-date 2026-01-01 --end-date 2026-01-31 --output jan_sms.csv

# Export for specific office
python3 export_sms.py --office-id 6194013244489728 --output office_sms.csv

Output: CSV file with columns:

• date — Timestamp
• from_number — Sender
• to_number — Recipient
• text — Message content
• status — Delivery status

Architecture

Dialpad SMS Skill
├── send_sms.py           # Send SMS (working)
├── make_call.py          # Make voice calls (working)
├── create_sms_webhook.py # Create webhook subscriptions (new)
├── export_sms.py         # Export historical SMS (new)
├── sms_sqlite.py         # SQLite storage with FTS5 (RECOMMENDED)
├── webhook_sqlite.py     # Webhook handler for SQLite
├── sms_storage.py        # Legacy JSON storage (deprecated)
└── webhook_receiver.py   # Legacy webhook handler