twilio-marketing-promotions-advisor

---
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)
```

From twilio/ai at 8aba46f, shown as plain text under its license: MIT (permissive). The license text is in LICENSE.

• SKILL.md13 KB · 11e04c0838ba
• agents/
• openai.yaml463 B · 0f58970eb252
• assets/
• icon-large.png9.6 KB · 0ba822e01172
• icon-small.png5.6 KB · 400e3f49b6c1

4 files, 28 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.