dialpad

name	dialpad
description	Send SMS and make voice calls via Dialpad API using task-focused wrappers backed by an OpenAPI-generated CLI.
homepage	https://developers.dialpad.com/

Dialpad Skill

Send SMS and make voice calls via the Dialpad API.

When to Use

Native tools: submit_draft (registered by this skill's dialpad-draft-callback plugin). Owned entrypoints: list_sms_thread.py, lookup_contact.py, poll_voicemails.py.

Use this skill to:

• Send SMS messages (individual or batch)
• Make voice calls (with TTS or custom voices)
• Manage contacts and organization settings
• Inspect SMS history through operator tooling when needed

Available Phone Numbers

Number	Purpose	Format
[phone]	Sales Team	Default for sales context
[phone]	Work/Personal	Default for work context
[phone]	Support SMS Only	SMS only (no voice)

Quick Start

Send SMS (explicit sender recommended):

bin/send_sms.py --to "[phone]" --from "[phone]" --message 'Hello from OpenClaw!'

Send an operator-approved SMS and close a shown approval draft (agent direct path):

bin/send_sms.py --to "[phone]" --from "[phone]" --message 'Exact approved text' --resolve-draft-id smsdraft_abc123 --approval-actor-id "telegram-user-123" --approval-actor-username "operator" --json

Create/approve an SMS draft (human approval path):

bin/create_sms_draft.py --thread-key "manual:thread" --to "[phone]" --from "[phone]" --message 'Exact draft text' --json
bin/approve_sms_draft.py smsdraft_abc123 --actor-id "telegram-user-123" --actor-username "operator" --approval-token "$DIALPAD_SMS_APPROVAL_TOKEN" --json

Group Intro (mirrored fallback):

bin/send_group_intro.py --prospect "[phone]" --reference "[phone]" --confirm-share --from "[phone]"

Make Call (TTS):

bin/make_call.py --to "[phone]" --text "This is a call from the agent."

List Recent Calls:

bin/list_calls.py --today --limit 20
bin/list_calls.py --hours 6 --missed --json

Get Call Transcript:

bin/get_call_transcript.py --call-id "call_123" --json
bin/get_call_transcript.py --last --with "[phone]" --json

Check SMS Thread History:

bin/list_sms_thread.py --phone "[phone]" --json

Sync Direct Dialpad SMS Sends:

bin/sync_sms_export.py --start-date 2026-05-13 --end-date 2026-05-13 --json

Create Contact:

bin/create_contact.py --first-name "Jane" --last-name "Doe" --phone "[phone]" --email "[e-mail]"

Update Contact:

bin/update_contact.py --id "contact_123" --phone "[phone]" --job-title "VP"

Key Rules

1. Destination policy: Outbound SMS and calls support NANP (+1) destinations only, including all NANP territories. Non-NANP international destinations are rejected before any Dialpad API request. Always use E.164 format (e.g., [phone]); SMS country inference normalizes ten-digit NANP input to explicit +1 E.164. The generated message schedules.send_now command is disabled because stored recipients cannot be validated locally; schedule updates must repeat phone recipients through --data as a JSON array; meeting updates must set call_out through --data as a JSON boolean; and generated meeting create/update commands cannot enable call-out.
2. Escaping: Use single quotes for inline --message values containing $ to prevent shell expansion (e.g., 'Price is $10').
3. Safer message input: Prefer --message-file or --message-stdin for pricing text, multi-line copy, or anything shell-sensitive.
4. Supported agent interface: use bin/*.py wrappers for normal work. They are the stable command contract for agents.
5. Operator-only surfaces: generated/dialpad and scripts/* are for manual troubleshooting, storage inspection, or operational maintenance, not normal agent task execution.
6. Auth canonical source: DIALPAD_API_KEY is canonical. DIALPAD_TOKEN is only needed for manual generated CLI troubleshooting (bridge command in Setup below).
7. SMS sender safety: --from and --profile work|sales are supported. Prefer explicit --from for deterministic routing.
   • --profile maps to configured env vars:
     • work: DIALPAD_PROFILE_WORK_FROM
     • sales: DIALPAD_PROFILE_SALES_FROM
   • default fallback order: DIALPAD_DEFAULT_FROM_NUMBER, then DIALPAD_DEFAULT_PROFILE
   • --allow-profile-mismatch permits explicit/profile mismatches when intentional
   • --dry-run prints sender resolution and the exact message/request preview without an API call

Reference Documentation

• references/api-reference.md — Wrapper behavior, operator CLI reference, Webhooks
• references/openclaw-integration.md — End-to-end setup guide for wiring this repo's webhook server to OpenClaw with human approval defaults
• references/sms-storage.md — SQLite commands, FTS5 search, legacy storage
• references/voice-options.md — List of available TTS voices (Budget & Premium)
• references/architecture.md — System architecture, wrappers, and CLI generation
• THEORY.MD — Design rationale: shell-corruption invariant, 401 classification, inbound-policy-once model

Operational Tools

Use these only for manual operator workflows, storage inspection, and maintenance:

python3 scripts/sms_sqlite.py list
python3 scripts/webhook_server.py

Setup

Required environment variable:

export DIALPAD_API_KEY="your_key"

Operator auth bridge for manual generated CLI troubleshooting:

export DIALPAD_TOKEN="${DIALPAD_TOKEN:-$DIALPAD_API_KEY}"

Optional:

export ELEVENLABS_API_KEY="your_key"
export DIALPAD_USER_MAP='{"[phone]": "5765607478525952"}'
export DIALPAD_PROFILE_WORK_FROM="[phone]"
export DIALPAD_PROFILE_SALES_FROM="[phone]"
export DIALPAD_DEFAULT_PROFILE="work"
export DIALPAD_DEFAULT_FROM_NUMBER="[phone]"
export DIALPAD_SMS_RECEIPT_LEDGER="/data/.openclaw/state/dialpad/sms-receipts.jsonl"
export DIALPAD_DRAFT_CALLBACK_URL="http://host.docker.internal:8888/internal/draft-callback"

For merged agent-draft flow, keep DIALPAD_DRAFT_CALLBACK_URL aligned with the OpenClaw dialpad-draft-callback plugin callbackUrl config. The default host.docker.internal URL is for gateway-container to host-webhook delivery.