Twilio -- Communications Integration Expert

---

name: twilio description: > Build SMS, voice, WhatsApp, and 2FA flows with Twilio's messaging and Verify APIs. USE WHEN: User needs SMS/voice/WhatsApp messaging, 2FA verification, IVR flows, or multi-channel notification systems with Twilio. DON'T USE WHEN: User needs email-only communication. Use Resend for transactional email. OUTPUTS: Messaging flows, TwiML voice configs, WhatsApp templates, Verify implementations, webhook handlers, multi-channel notification architectures. version: 1.1.0 author: SpookyJuice tags: [twilio, sms, voice, whatsapp, verify, messaging] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1" content_hash: "sha256:33778d6f73be77b3ba4fb6f2dcc31dd95e074c43f3cdcb551d012381a0f0c9da"

#‍​‌‌​‌‌‌‌​‌‌‌​​‌‌​‌‌‌​​​​​‌‌‌​​‌‌​​‌‌‌​‌​​​‌‌​​​‌​​‌‌‌​‌​​‌‌‌​​‌‌​‌‌​‌​‌​​​‌​‌‌​‌​​‌‌‌​​​​​‌‌​​​​​​‌‌​‌‌‌​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌‌​​‌‌​​‌‌​‌‌​​​‌‌‍ Twilio

Version: 1.1.0 Price: $14 Type: Skill

Description

Production multi-channel communication with Twilio — beyond client.messages.create(). The API catalog spans 15+ products organized by product, not by what you're building, so wiring up a verification flow that falls back from SMS to voice to WhatsApp means stitching together three separate guides and handling edge cases none of them mention. The real complexity is in the interaction between channels: webhook race conditions between SMS delivery receipts and WhatsApp session windows, TwiML call flows that need to handle DTMF input without spaghetti nesting, and Verify rate limits that vary by country and silently drop OTPs if you exceed them.

Prerequisites

• Twilio account with API access
• Account SID: TWILIO_ACCOUNT_SID
• Auth Token: TWILIO_AUTH_TOKEN
• Phone number(s) provisioned for SMS/Voice
• For WhatsApp: approved WhatsApp Business sender
• Twilio CLI: npm install -g twilio-cli

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Set environment variables:

   export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   export TWILIO_AUTH_TOKEN="your-auth-token"
   export TWILIO_PHONE_NUMBER="+1234567890"
   

3. Reload OpenClaw

Commands

• "Set up SMS messaging for [use case]"
• "Build a voice IVR flow for [business]"
• "Implement WhatsApp Business messaging for [use case]"
• "Add 2FA/OTP verification with Verify"
• "Build multi-channel notifications for [alert type]"
• "Handle inbound messages with webhook routing"
• "Debug this Twilio error: [error code]"

Workflow

SMS/MMS Messaging

1. Messaging Service setup — create a Messaging Service instead of sending from raw phone numbers. Messaging Services handle number pooling, sticky sender (same number per recipient), and compliance features automatically. Associate your phone numbers with the service.
2. Outbound messaging — send via Messaging Service SID, not phone number. Include statusCallback URL to receive delivery receipts. Handle status events: queued → sent → delivered (or failed/undelivered). Store the message SID for tracking.
3. Inbound handling — configure your Messaging Service webhook URL for incoming messages. Parse: Body, From, To, NumMedia (for MMS), and MediaUrl0-MediaUrlN. Respond with TwiML <Message> for auto-replies or return 204 for no reply.
4. Conversation tracking — use Twilio Conversations API for stateful threads (multi-party, cross-channel). For simple request-reply patterns, track by From number with a session timeout. Store conversation state in your database, not in Twilio.
5. Compliance — implement opt-out handling: watch for STOP/UNSUBSCRIBE keywords (Twilio handles these automatically for US numbers but you should track opt-outs in your system too). Include opt-out instructions in marketing messages. Respect quiet hours per timezone.
6. Rate limiting — Twilio enforces per-second sending limits by number type: long codes (1 msg/sec), toll-free (up to 40 msg/sec), short codes (100+ msg/sec). For bulk sends, use Messaging Service with number pooling and stagger sends across seconds.

Voice Call Routing

1. TwiML basics — voice calls are controlled by TwiML (Twilio Markup Language) returned from your webhook. Key verbs: <Say> (text-to-speech), <Play> (audio file), <Gather> (collect DTMF or speech input), <Dial> (connect to another party), <Record> (record the call).
2. IVR tree design — use <Gather> with action URL for each menu level. Set numDigits, timeout, and input="dtmf speech" for flexibility. Handle: valid input (route to next menu/agent), invalid input (replay menu), no input (timeout, offer help), and * or # shortcuts for power users.
3. Call queuing — use <Enqueue> to place callers in a named queue with hold music. Agents connect via <Dial><Queue>. Configure: max wait time, queue size limits, position announcements, and estimated wait time based on average handle time.
4. Recording management — <Record> with recordingStatusCallback for async notification when recording is ready. Store recordings in your own storage (S3/R2) — don't rely on Twilio's retention. Implement transcription with transcribe="true" or use a dedicated service for better accuracy.
5. Call flow resilience — always set action URL fallbacks so TwiML failures don't drop calls. Use <Say> fallback messages for error conditions. Log call events via statusCallback for debugging. Handle: caller hangup during menu, agent unavailable, and transfer failures.
6. Conference calls — <Dial><Conference> for multi-party calls. Configure: moderator controls (mute/unmute), start/end on moderator join/leave, recording, and participant limits. Use coach mode for supervisor whisper (agent hears, caller doesn't).

Verify 2FA/OTP

1. Service configuration — create a Verify Service in the Twilio console or via API. Configure: code length (4-10 digits), code TTL (default 10 minutes), and friendly name (shown in SMS: "Your [FriendlyName] code is 123456").
2. Verification flow — start: client.verify.v2.services(SID).verifications.create({ to, channel: 'sms' }). Check: client.verify.v2.services(SID).verificationChecks.create({ to, code }). Status returns approved or pending — never reveal whether the code was correct or expired to prevent enumeration.
3. Channel fallback chain — attempt SMS first. If delivery fails or user requests, fall back to voice call (Twilio reads the code aloud). For supported carriers, use Silent Network Auth (zero-interaction verification). Configure attempt order in the Verify Service settings.
4. Rate limiting and fraud prevention — Verify has built-in rate limits per phone number and per service. Enable Fraud Guard to block high-risk country codes and detect pumping attacks (bots triggering thousands of SMS). Set per-country rate limits for known fraud origins.
5. Custom templates — customize the SMS message template per locale. Include: the code, your app name, and expiration time. For voice channel, customize the speech pattern and language. Support multiple languages with locale-based routing.
6. Verification analytics — track: verification attempt rate, success rate (target >95%), channel conversion (how often SMS succeeds vs. requiring voice fallback), time-to-verify (users should complete in <30 seconds), and fraud block rate.

Output Format

📱 TWILIO — [IMPLEMENTATION TYPE]
Project: [Name]
Channels: [SMS/Voice/WhatsApp/Verify]
Date: [YYYY-MM-DD]

═══ CONFIGURATION ═══
| Resource | SID | Type | Purpose |
|----------|-----|------|---------|
| [resource] | [SID] | [type] | [purpose] |

═══ MESSAGING FLOW ═══
[Flow: trigger → channel selection → send → delivery callback → status update]

═══ WEBHOOK ENDPOINTS ═══
| Endpoint | Method | Event | Action |
|----------|--------|-------|--------|
| [url] | POST | [event] | [handler action] |

═══ CHANNEL STRATEGY ═══
| Channel | Priority | Cost/msg | Fallback |
|---------|----------|----------|----------|
| SMS | Primary | $0.0079 | Voice |
| Voice | Secondary | $0.013/min | WhatsApp |
| WhatsApp | Tertiary | $0.005 | Email |

═══ COMPLIANCE ═══
☐ Opt-out handling configured
☐ Quiet hours enforced
☐ Rate limits set per channel
☐ Consent records stored

Common Pitfalls

• Sending from phone number instead of Messaging Service — raw numbers don't get number pooling, sticky sender, or compliance features. Always use Messaging Service SID for production.
• WhatsApp 24-hour session window — after 24 hours of no customer-initiated message, you can only send pre-approved template messages. Sending free-form text outside the window silently fails or gets rejected.
• TwiML webhook timeout — Twilio waits 15 seconds for your TwiML response. If your server takes longer, the call drops. Return TwiML fast, then do processing async.
• Verify rate limits by country — some countries have strict per-number SMS limits. Sending 10 OTPs in a minute to the same number triggers carrier-level blocking that Twilio can't override. Implement UI-level rate limiting.
• Recording storage costs — Twilio charges for recording storage beyond 10,000 minutes. Download and store recordings in your own S3/R2 bucket, then delete from Twilio.

Guardrails

• Never exposes Auth Token. The Auth Token is server-only. Client-side code uses API Key SID + Secret pairs with scoped permissions, never the master Auth Token.
• Webhook signatures verified. Every incoming webhook validates the X-Twilio-Signature header using your Auth Token. Unverified requests are rejected.
• Opt-out lists enforced. Every outbound message checks against opt-out records. Users who send STOP are never messaged again without explicit re-opt-in.
• Cost tracking per channel. Every implementation includes per-message and per-minute cost tracking. No surprise bills from runaway notification loops.
• Rate limits respected. All sending operations use queues with rate limiting matching number type and channel capacity. No burst sending that triggers carrier blocking.
• Sensitive data redacted. Phone numbers are partially masked in logs ("+1***567890"). Full numbers only stored encrypted in your database, never in application logs.
• Consent verified before sending. Every outbound message confirms recipient opt-in consent exists in your records before delivery. No messages are sent to numbers without documented TCPA-compliant consent, preventing regulatory violations and carrier penalties.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice — https://www.shopclawmart.com