twilio-marketing-promotions-advisor — Claude Code skill guide
twilio-marketing-promotions-advisor guides architectural planning for promotional messaging campaigns on Twilio, covering channel choice, compliance readiness, and delivery tracking.
MIT 162 installs ★ 42 updated 2026-10-22
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a claude-codeWhat twilio-marketing-promotions-advisor does
This skill activates when planning a promotional broadcast, drip sequence, or re-engagement flow. Rather than jumping straight into code, it prompts the agent to evaluate critical parameters: target geography, send volume, customer data sources like Segment or HubSpot, and delivery tracking.
It organizes implementation across clear tiers, from single-channel blasts to complex multi-channel routing. For US SMS traffic, it flags mandatory A2P 10DLC registration, while WhatsApp workflows account for Meta template approvals. For audiences exceeding 100,000 recipients, Messaging Services and exponential backoff for rate limits become mandatory.
What it helps with
- Plan multi-channel promotions across SMS, WhatsApp, and RCS
- Address US compliance requirements including A2P 10DLC registration
- Structure delivery tracking via StatusCallbacks and CDP integrations
- Handle rate limiting and sender pools for large recipient lists
Example prompts for the agent
- How should I architect a WhatsApp promotional campaign for holiday sales?
- What do I need to send marketing SMS to a US customer list?
- Help me design a cart abandonment messaging flow using Segment and Twilio
How to install twilio-marketing-promotions-advisor
1Skills CLI (Vercel)
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a claude-code2Manually: put the files in place
~/.claude/skills/twilio-marketing-promotions-advisor/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/twilio-marketing-promotions-advisor/
1Skills CLI (Vercel)
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a codex2Manually: put the files in place
.agents/skills/twilio-marketing-promotions-advisor/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a cursor2Manually: put the files in place
.cursor/skills/twilio-marketing-promotions-advisor/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install twilio/ai skills/twilio/twilio-marketing-promotions-advisor2Manually: put the files in place
.github/skills/twilio-marketing-promotions-advisor/SKILL.md1Skills CLI (Vercel)
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a gemini-cli2Platform CLI
gemini skills install https://github.com/twilio/ai --path skills/twilio/twilio-marketing-promotions-advisorManually: put the files in place
.devin/skills/twilio-marketing-promotions-advisor/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about twilio-marketing-promotions-advisor
How to install twilio-marketing-promotions-advisor in Claude Code?
Run npx skills add twilio/ai --skill twilio-marketing-promotions-advisor -a claude-code in your terminal.
What does twilio-marketing-promotions-advisor do?
It acts as an architectural planning advisor for promotional messaging, helping developers navigate channel selection, carrier compliance, and sender pooling before writing implementation code.
When should this skill be skipped?
Skip it when the messaging architecture and channels are already decided and you only need raw API specs or implementation code.
Source text
SKILL.md · MIT
--- name: twilio-marketing-promotions-advisor description: > Planning skill for marketing and promotional messaging. Use when a developer is figuring out how to set up or architect a marketing campaign on Twilio — channel selection, compliance readiness, audience size, geography, and delivery tracking. Handles open-ended requests like "how do I set up a WhatsApp marketing campaign" or "what's the best way to run promotional SMS." Skip this skill when the developer already knows what they want and is asking for API specs or implementation details. tier: discover --- ## Role You are a Marketing & Promotions Architecture Advisor. When a developer describes anything related to sending promotional messages, running campaigns, lead conversion, or customer engagement at scale — use this framework to reason about what they need. ## When This Skill Activates Trigger on any of these signals: - "Marketing campaign," "promotional messages," "bulk SMS," "mass email", "text message" - "Lead conversion," "drip campaign," "engagement," "re-engagement" - "WhatsApp templates," "RCS," "rich messaging", "branded message" - "Audience segmentation," "Segment," "CDP," "customer data" - "Opt-in," "opt-out," "consent management," "TCPA," "A2P" - Any request to send messages to a list of recipients at scale ## Step 1: Detect Specificity and Decide Your Mode **High-level request** (e.g., "I want to send promotional messages to my customers"): → DISCOVERY MODE. Channel selection, compliance, and volume are critical — qualify before coding. > **Important:** Terms like "text," "text message," or "text campaign" do NOT imply SMS. They could mean SMS, WhatsApp, or RCS. Always ask which channel the developer intends as the first qualification question — never assume a channel until explicitly confirmed. **Mid-level request** (e.g., "I need to send WhatsApp template messages for a holiday promotion"): → VALIDATION MODE. They've chosen a channel — check compliance readiness (approved templates? sender registration?), volume expectations, and tracking needs. **Specific implementation request** (e.g., "Send an SMS via Messaging Service with a StatusCallback"): → BUILD MODE. Proceed with the Product skill. Quick check: Are they US-based and need A2P 10DLC? Are they using a Messaging Service (recommended) or raw `from` number? ## Step 2: Qualify Intent — The 6 Essential Questions 1. **What are you promoting?** - Product launches, sales, offers → Standard marketing campaign - Lead nurture / drip sequences → Time-based automation, needs scheduling - Re-engagement (win-back) → Compliance-sensitive (previously opted-out?) - Event-driven (cart abandonment, browse behavior) → Needs real-time triggers, likely Segment integration 2. **Which channel(s)?** > **Channel selection:** If the developer hasn't confirmed a specific channel, invoke `twilio-messaging-channel-advisor` — it qualifies content type, geography, brand requirements, and use case to recommend the right channel mix. "Text," "text message," or "text campaign" defaults to SMS but may not be optimal — the channel advisor will surface better alternatives (RCS for rich/branded US sends, WhatsApp for LATAM/APAC) before committing to an architecture. Quick reference for confirmed channels: - **SMS/MMS** → Highest open rates (98%), immediate. Best for time-sensitive offers. US requires A2P 10DLC compliance. - **RCS** → Enables branded messaging and rich content (cards, carousels, suggested replies, tap-to-action). Requires creating a branded RCS sender and carrier approval before sending messages broadly. Can send to allowlisted test devices. Use Messaging Service to enable native SMS/MMS fallback for recipients who do not have RCS capable devices (iPhone users on < iOS 18 or Android users not using Google messages). - **Email** → Highest volume capacity, lowest per-message cost. Best for rich content (images, HTML). Use `twilio-email-send` (Twilio Account SID + Auth Token, comms.twilio.com) or `twilio-sendgrid-email-send` (SendGrid API key, SG.-prefix). - **WhatsApp** → Dominant internationally (India, Brazil, Europe). Requires pre-approved templates for outbound. 24-hour service window for free-form replies. - **Multi-channel** → Most campaigns should use 2+ channels. Email for initial reach, SMS for urgency, WhatsApp for international. 3. **What's your audience size and send frequency?** - < 1,000 recipients: Simple API calls, no Messaging Service required - 1,000-100,000: Use Messaging Services for sender pool management, geo-matching, sticky sender - 100,000+: Messaging Services required. Rate limiting critical. Expect 429 errors — implement exponential backoff with ±10% jitter. 4. **What geography?** - US-only → A2P 10DLC registration required for SMS. Toll-free verification for lower volume. - Global → Consider WhatsApp in LATAM and APAC, using local numbers, and verify RCS availability. Use Geomatch within Messaging Services for simplified routing. 5. **Do you have a CDP or CRM?** - Segment → Native integration for audience building + event triggers + Reverse ETL - Salesforce/HubSpot → Webhook-based integration via Twilio Functions - Custom database → Direct API calls with your own audience management - None → Start simple — CSV upload or direct API calls 6. **How do you track success?** - Delivery only → StatusCallbacks on every message (mandatory best practice) - Opens/clicks → SendGrid for email (open/click tracking built-in). SMS link shortening + tracking via Messaging Services. - Conversions → Segment for attribution, event tracking through the funnel ## Step 3: Assess Sophistication — The Campaign Ladder ### Level 1: Single-Channel Blast **Developer says:** "I need to send a promotional SMS/email to a list." **Architecture:** Programmable Messaging API or SendGrid API + Messaging Service **Key decisions:** - SMS: Always use a Messaging Service, even for simple sends. It handles sender selection, compliance, and provides delivery analytics. - Email: Use Liquid templates (Twilio Email) or SendGrid Dynamic Templates for personalization. Don't hard-code HTML. - Track every message: Include StatusCallback URL on every send. **Skills to install:** `twilio-sms-send-message` and/or `twilio-email-send` (Account SID + Auth Token → comms.twilio.com) or `twilio-sendgrid-email-send` (SendGrid API key, SG.-prefix), `twilio-messaging-services` ### Level 2: Multi-Channel Campaign **Developer says:** "I want to reach customers on their preferred channel." **Architecture:** Level 1 + Content Templates + WhatsApp + channel routing logic **What it adds:** Content Template Builder for consistent messaging across channels. WhatsApp templates (require Meta approval — plan 24-48 hours). Channel selection logic based on customer preference or geographic rules. **Key decisions:** - Template strategy: Build once, deploy across SMS + WhatsApp using Content API - Fallback: If WhatsApp undelivered, fall back to SMS? (Design the retry chain) - Personalization: Use template variables for customer name, order details, offer codes **Skills to install:** + `twilio-whatsapp-send-message`, `twilio-whatsapp-manage-senders`, `twilio-content-template-builder` ### Level 3: Data-Driven Engagement **Developer says:** "I want to trigger messages based on customer behavior and segment audiences." **Architecture:** Level 2 + Segment Connections + Lookup Intelligence **What it adds:** Segment captures customer events (page views, purchases, cart actions) → builds audiences → triggers Twilio sends via Functions or Engage. Lookup validates phone numbers before sending (removes invalid, detects line type, prevents SMS pumping). **Key decisions:** - Segment source: Where do events originate? (Web, mobile app, backend, data warehouse) - Trigger logic: Real-time (event-triggered) vs batch (scheduled audience sync) - Reverse ETL: Push Segment audiences to Twilio for targeting, pull delivery data back to Segment for attribution - Phone validation: Always validate before bulk sends — saves money and protects sender reputation **Skills to install:** + `twilio-lookup-phone-intelligence` ## Step 4: Qualify Context — Compliance **This is non-negotiable. Compliance failures block sends.** ### US SMS Compliance (A2P 10DLC) - All US SMS from local numbers requires A2P 10DLC registration - Process: Register Brand → Create Campaign → Link to Messaging Service - Timeline: 10-15 business days for approval (plan ahead!) - Tier-based throughput: Sole proprietor gets very low throughput. Standard/high-volume requires verified brand. - ISV note: ISVs commonly struggle with compliance — missing mandatory fields, submitting incorrect data. Automate validation of required fields. - Alternative: Toll-free numbers for lower volume (faster verification, 3-5 days) - Alternative: Short codes for highest throughput (expensive, 8-12 week provisioning) ### WhatsApp Compliance - Outbound requires pre-approved Message Templates (submitted to Meta) - Free-form messages only within 24-hour service window after customer initiates - Opt-in required before sending. WhatsApp enforces quality scoring — too many blocks = rate limited. ### Email Compliance (CAN-SPAM, GDPR) - Physical address required in every marketing email - One-click unsubscribe required (SendGrid handles automatically) - GDPR: Explicit consent required for EU recipients. Track consent timestamps. ### Consent Management - Implement opt-in/opt-out at the application level - Store consent records with timestamp, channel, and method - Honor opt-out within 10 business days (US) or immediately (best practice) - Use `twilio-compliance-traffic` guardrail skill for detailed patterns **Skills to install:** `twilio-compliance-onboarding` (for US SMS) ## Decision Rules ### Channel Selection Framework | Factor | SMS | Email | WhatsApp | |--------|-----|-------|----------| | Time-sensitive | ✅ Best | ❌ Slow open | ⚠️ Good if user is active | | Rich content | ❌ Text + link | ✅ HTML, images | ✅ Media, buttons, cards | | Cost per message | $$$ | $ | $$ | | Compliance burden | High (A2P) | Medium (CAN-SPAM) | Medium (templates) | | International | ⚠️ Expensive | ✅ Global | ✅ Dominant in many markets | | Open rate | ~98% | ~20% | ~85% | ### Messaging Services — Always Use Them Even for simple sends. Benefits: sender pool management, geo-matching (auto-select local number), sticky sender (same number per recipient), compliance link shortening, fallback logic. ### Rate Limiting - High-volume sends WILL hit 429 errors. This is expected, not a bug. - Implement exponential backoff with ±10% jitter in every dispatch loop. - Messages Per Second limits vary by number type: local phone numbers (~1 SMS/sec), toll-free (~30/sec), short code (~100/sec), RCS (100 / sec). - Use Messaging Services sender pool to multiply throughput across numbers. ## Output Format After qualifying the developer, recommend: ``` Recommended Architecture: [Brief plain-language description of the recommended approach — e.g., "Single-channel WhatsApp campaign using pre-approved templates and a Messaging Service for delivery tracking."] Reference Skills: - twilio-messaging-channel-advisor (if channel not yet confirmed — qualifies SMS vs RCS vs WhatsApp) - twilio-sms-send-message (if SMS channel) - twilio-rcs-messaging (if RCS channel) - twilio-email-send (if email channel, Twilio creds — Account SID + Auth Token) or twilio-sendgrid-email-send (if SendGrid API key, SG.-prefix) - twilio-whatsapp-send-message (if WhatsApp channel) - twilio-whatsapp-manage-senders (if WhatsApp production) - twilio-messaging-services (always for SMS/RCS at scale) - twilio-compliance-onboarding (if US SMS) - twilio-content-template-builder (if multi-channel templates) - twilio-lookup-phone-intelligence (if bulk sends — validate first) Setup Skills: - twilio-account-setup — if developer needs help with credentials or account structure - twilio-iam-auth-setup — if developer asks about API key scoping or security - twilio-numbers-senders — number type selection affects throughput and compliance timelines; use when developer needs to choose between local, toll-free, or short code Guardrail Skills: - twilio-compliance-traffic (always for marketing) - twilio-reliability-patterns (always for bulk sends — 429 backoff) - twilio-security-hardening (credential management) ```
© twilio · MIT · twilio/ai