Twilio Hub

Twilio is the voice infrastructure and A2P SMS anchor for OpenClaw. It handles inbound/outbound voice calls via TwiML, SMS delivery via the Programmable SMS API, and serves as the 10DLC registration authority for the entire conversational SMS compliance envelope. This hub is the cluster anchor for both the SMS/Carrier compliance cluster and the Voice subsystem cluster. Read this hub first before any voice workflow change, SMS compliance decision, or 10DLC-related work. Owned by Henry Hill; handler maintained in twilio-voice-handler.js.

---

⚠️ Compliance Alert: A2P 10DLC Repeat-Denial — TCPA Risk Uncapped

Status: ACTIVE BLOCKER (as of 2026-05-03)

A2P 10DLC campaign registration has experienced a repeat denial. This has the following consequences:

1. TCPA risk is uncapped — sending conversational A2P SMS without an approved 10DLC campaign creates uncapped TCPA liability. Each non-compliant message = potential $500–$1,500 statutory damage.
2. ALL OSIL conversational SMS tiers are gated — the OpenClaw Self-Improvement Layer (OSIL) conversational SMS pipeline cannot go live until 10DLC approval is confirmed.
3. Both SMS channels affected — salesmsg and openphone-quo share the same compliance envelope. The Twilio 10DLC denial affects the entire SMS/Carrier cluster.

Resolution path:

• Active plan: osil-twilio-10dlc-resubmission-2026-05-03 sub-project B14
• Pending: B14a Henry signoff required before resubmission
• Do NOT launch any new conversational SMS campaign until B14 resolves
• Reference compliance-gates for the 5-gate pre-send enforcement layer

Henry action required: Review B14 in osil-twilio-10dlc-resubmission-2026-05-03 and provide B14a signoff for resubmission package.

---

Quick reference

Field	Value
Vendor	Twilio (twilio.com)
URL	https://api.twilio.com/2010-04-01
KB doc	API · WEBHOOKS
Auth method	HTTP Basic Auth (AccountSid:AuthToken) for REST API; HMAC-SHA1 for webhook signature validation
Auth credential (Account SID)	op://Aurora/twilio/account-sid
Auth credential (Auth Token)	op://Aurora/twilio/auth-token
Cred-proxy port	n/a (until B1-B6 ratified)
Webhook port	:18797
Webhook handler	twilio-voice-handler (twilio-voice-handler.js — dual-host)
Webhook auth	✅ HMAC-SHA1 — HMAC-SHA1(AuthToken, URL + sorted POST params); verified via X-Twilio-Signature header
Webhook dedup table	processed_webhook_events (24h TTL)
Tunnel paths (canonical)	/voice, /voice/webhook, /voice/status, /voice/recording-complete, /voice/transcription, /sms, /sms/webhook, /sms/status — all on https://webhook.reri.co/
Tunnel paths (fallback)	/sms, /voice on https://srv1347501.tailb025a7.ts.net/ (dual-host; untested for Tailscale path-strip with sorted-params HMAC)
Outbound API base	https://api.twilio.com/2010-04-01/Accounts/{AccountSid}
Active outbound numbers	+1 (949) 779-8471 (primary) · +1 (844) 688-3807 (toll-free)
Rate limits	REST API: 1 req/s default per phone number; burst handled by Twilio queue
Rate-limit action	429 → exponential backoff (3 retries), Discord ops alert
A2P 10DLC status	⚠️ Repeat denial — TCPA risk uncapped (see Compliance Alert above)
Cost	Voice: per-minute; SMS: per-segment ($0.0075 outbound US); see Twilio billing
Backup/recovery	Twilio-owned; no local message backup; voice recordings stored in Twilio cloud (configurable retention)
Discord alert channel	ops
Drift cadence	Weekly (security-audit-funnel.timer)
Process manager	PM2 (twilio)
Status	production

Components

• webhooks/twilio-voice-handler.js — unified voice + SMS webhook handler on :18797; dual-host (handles both Cloudflare Tunnel canonical URL and Tailscale fallback URL for HMAC validation)
• HMAC validation: URL must match provider-registered URL exactly — handler uses dual-URL candidate list to accommodate both webhook.reri.co and Tailscale fallback
• TwiML response: handler returns XML for call handling (<Say>, <Gather>, <Dial>, <Hangup>)
• Supabase tables: twilio_calls, twilio_sms, omni_events, processed_webhook_events (dedup)
• systemd/PM2 unit: twilio (PM2) — process manager for handler on :18797

Webhook endpoints (FUNNEL-REGISTRY.md approved)

Path	Event	Status
/voice/webhook	Inbound call	approved
/voice/status	Call status callback	approved
/voice/recording-complete	Recording ready	approved
/voice/transcription	Transcription ready	approved
/sms/webhook	Inbound SMS	approved
/sms/status	SMS delivery status	approved

All paths proxied via Cloudflare Tunnel reri-api → https://webhook.reri.co/. Handler validates X-Twilio-Signature HMAC-SHA1 on every request.

Registered phone numbers

Number	SID	Uses
+1 (949) 779-8471	PN728d17f512c2e9617cf5a9d8f2d7b784	Primary voice + SMS; voice_url + sms_url → webhook.reri.co
+1 (844) 688-3807	PNddaa5f2ef9fba79412e3fb7c06e86b43	Toll-free; voice_url + sms_url → webhook.reri.co

How it’s used

• Inbound call: Twilio fires POST /voice/webhook → handler returns TwiML (<Gather> + <Say>) → call connected or forwarded to agent
• Outbound call: POST /Accounts/{SID}/Calls.json with Url (TwiML endpoint) + To + From → handler manages call flow
• Inbound SMS: Twilio fires POST /sms/webhook → handler writes to omni_events → acquisitions agent dispatch via OpenClaw gateway (:18789)
• Outbound SMS: POST /Accounts/{SID}/Messages.json — note: A2P 10DLC required for campaign SMS; conversational SMS gated until B14 resolves
• Recording: call.completed → Twilio fires /voice/recording-complete → handler fetches recording URL → stores in Supabase
• Agents involved: acquisitions agent (voice callbacks), Aurora (orchestration), atlas agent (inbound call routing decisions)
• Failure mode: HMAC validation failure → 403; check that FUNNEL-REGISTRY URL matches Twilio-registered webhook URL exactly (including https:// prefix, no trailing slash)
• Dual-host note: Tailscale fallback URL /voice is untested for HMAC with sorted-params — if failover to Tailscale is needed, test HMAC candidate URLs before relying on it
• Success criteria: inbound event validates HMAC → handler writes to processed_webhook_events (dedup) + omni_events → TwiML response returned within 5s (Twilio timeout is 15s)

Cross-links

Agents that touch this

• _summary — voice callback handling; fallback from SMS
• _summary — orchestration; routes call events to sub-agents
• _summary — inbound call routing decisions; escalation path

Skills that invoke this

• acquisitions-outreach — may initiate outbound voice calls (fallback path)
• acquisitions-followup — inbound call events processed by follow-up stage router

Plans that govern this

• osil-twilio-10dlc-resubmission-2026-05-03 — B14 ACTIVE BLOCKER — 10DLC repeat-denial; B14a Henry signoff pending; gates all OSIL SMS tiers
• openclaw-self-improvement-layer-2026-05-03 — OSIL conversational SMS pipeline gated on B14 resolution
• openclaw-fragmentation-fix-2026-05-01 — G-SERVICE-PRE-START-DOC and G-NO-PLAINTEXT-CREDS enforcement

Feedback rules

• feedback_action_gate_violation_repeated — service restarts require explicit Henry auth; do not restart twilio PM2 process without confirmation
• feedback_no_plaintext_creds — op://Aurora/twilio/account-sid and op://Aurora/twilio/auth-token; never hardcode in handler or config

KB / source docs

• API — full REST API reference, auth, voice/SMS/WhatsApp endpoints
• WEBHOOKS — event types, HMAC-SHA1 signing, TwiML response patterns, webhook configuration

System maps

• vm-integrations-overview — full integration topology
• voice-call-routing — voice call routing diagram
• sms-inbound-flow — inbound SMS routing (Twilio + Quo + SalesMsg)

Related: SMS/Carrier compliance cluster

This hub is the cluster anchor for the SMS/Carrier compliance cluster.

• twilio — this hub — voice + A2P SMS; 10DLC registration authority; ⚠️ repeat-denial active
• salesmsg — primary blast channel (SalesMsg); ?secret= auth (NOT HMAC)
• openphone-quo — acquisitions SMS + voice; shares 10DLC compliance envelope
• compliance-gates — 5-gate pre-send enforcement (gate-computer, compliance-gate, blast-safety, thread-context, response-generator); B14 adds 10DLC gate
• osil-twilio-10dlc-resubmission-2026-05-03 — active blocker plan; Henry B14a signoff required

Related: Webhook/tunnel cluster

• cloudflare — Cloudflare Tunnel reri-api; all Twilio paths under webhook.reri.co; FUNNEL-REGISTRY.md is authoritative; WAF IP filtering (N/A for Twilio — no published IP ranges); DocuSign WAF IP allowlist on same WAF instance (90-day rotation)
• salesmsg — sibling handler on :18793
• openphone-quo — sibling handler on :18792
• hubspot — sibling handler on :18790

Related: Voice subsystem cluster

This hub is the cluster anchor for the Voice subsystem.

• twilio — this hub — primary voice infrastructure; HMAC-SHA1; TwiML; 10DLC
• openphone-quo — Quo voice events (call.ringing, call.completed, transcripts, summaries); separate HMAC signing
• livekit-deferred — real-time voice/video (WebRTC); deferred to OSIL Phase 6 (B10 ratified); not operational; do not build against until nemoclaw-audit-2026-05-03 B10 ships in Wave 2 or 3
• nemoclaw-audit-2026-05-03 — NemoClaw audio/LLM pipeline; forward-ref; not yet operational

Open issues / TODOs

• B14 BLOCKER: Henry B14a signoff required for 10DLC resubmission — see osil-twilio-10dlc-resubmission-2026-05-03
• Verify Tailscale fallback /voice and /sms paths produce valid HMAC candidates (sorted-params candidate list in handler covers both hosts?)
• Confirm WhatsApp webhook path registered and in FUNNEL-REGISTRY.md (WhatsApp setup was in-progress per API.md — current status unknown)
• Add Twilio credentials to cred-proxy rotation plan when B1-B6 ratified (see 1password)
• Review security-audit-funnel.timer output for Twilio path drift — FUNNEL-REGISTRY shows 7 Twilio paths; confirm all 7 are still live

Recent activity

• 2026-05-03: hub created (W1-S2); 10DLC compliance alert section added per mandatory PF-A scope insert
• 2026-04-21: FUNNEL-REGISTRY.md updated; Twilio paths migrated to Cloudflare Tunnel canonical URL
• 2026-02-27: KB API.md + WEBHOOKS.md last updated