dialpad

Dialpad Skill

Send SMS and make voice calls via the Dialpad API.

Available Phone Numbers

Number	Purpose	Format
(415) 520-1316	Sales Team	Default for sales context
(415) 360-2954	Work/Personal	Default for work context
(415) 991-7155	Support SMS Only	SMS only (no voice)

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)

Voice	Style	Notes
Eric ⭐	Male, smooth, trustworthy	Low-cost, available!
Daniel	Male, British, steady	Budget
Sarah	Female, mature	Budget
River	Male, neutral	Budget
Alice	Female, clear	Budget
Brian	Male, deep	Budget
Bill	Male, wise	Budget

Premium Voices (Higher Quality)

Voice	Style	Notes
Adam	Male, deep, clear	Best for professional
Antoni	Male, warm	Friendly tone
Bella	Female, soft	Warm, engaging

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)

Name	Phone	User ID
Martin	(415) 360-2954	5765607478525952
Lilla	(415) 870-1945	5625110025338880
Scott	(415) 223-0323	5964143916400640

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

Error	Meaning	Action
invalid_destination	Invalid phone number	Verify E.164 format
invalid_source	Caller ID not available	Check --from number assignment
no_route	Cannot deliver	Check carrier/recipient
user_id required	Missing user ID	Use --from with known number

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