twilio-messaging-services

What this skill does

## Overview

A Messaging Service groups senders (phone numbers, short codes, toll-free numbers) with shared configuration. Send via `messagingServiceSid` instead of a specific `from` number — Twilio picks the best sender automatically.

**Use a Messaging Service for all production sends.** Beyond sender pools, it unlocks compliance toolkit, SMS pumping protection, link shortening, message scheduling, and intelligent alerts. For channel selection guidance, see `twilio-messaging-overview`.

---

## Prerequisites

- Twilio account with at least one SMS-capable phone number
  — New to Twilio? See `twilio-account-setup`
- Environment variables:
  - `TWILIO_ACCOUNT_SID`
  - `TWILIO_AUTH_TOKEN`
  — See `twilio-iam-auth-setup` for credential setup and best practices
- SDK: `pip install twilio` / `npm install twilio`

---

## Quickstart

**Python**
```python
import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

# Step 1: Create the service
service = client.messaging.v1.services.create(
    friendly_name="Production Notifications Service"
)
print(service.sid)  # MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx — save as MESSAGING_SERVICE_SID

# Step 2: Add a phone number
client.messaging.v1 \
    .services(service.sid) \
    .phone_numbers \
    .create(phone_number_sid="PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

# Step 3: Send via the service
message = client.messages.create(
    messaging_service_sid=service.sid,
    to="+15558675310",
    body="Your order has shipped."
)
print(message.sid)
```

**Node.js**
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

// Step 1: Create the service
const service = await client.messaging.v1.services.create({
    friendlyName: "Production Notifications Service",
});
console.log(service.sid);

// Step 2: Add a phone number
await client.messaging.v1
    .services(service.sid)
    .phoneNumbers.create({ phoneNumberSid: "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" });

// Step 3: Send via the service
const message = await client.messages.create({
    messagingServiceSid: service.sid,
    to: "+15558675310",
    body: "Your order has shipped.",
});
console.log(message.sid);
```

---

## Key Patterns

### Create Service with Webhooks and Features

**Python**
```python
service = client.messaging.v1.services.create(
    friendly_name="Marketing Campaigns",
    inbound_request_url="https://yourapp.com/sms/inbound",
    status_callback="https://yourapp.com/sms/status",
    sticky_sender=True,
    area_code_geomatch=True,
    validity_period=14400
)
```

**Node.js**
```node
const service = await client.messaging.v1.services.create({
    friendlyName: "Marketing Campaigns",
    inboundRequestUrl: "https://yourapp.com/sms/inbound",
    statusCallback: "https://yourapp.com/sms/status",
    stickySender: true,
    areaCodeGeomatch: true,
    validityPeriod: 14400,
});
```

### Optional Features

| Feature | Parameter | Description |
|---------|-----------|-------------|
| Sticky Sender | `sticky_sender` | Same sender for same recipient |
| Area Code Geomatch | `area_code_geomatch` | Match sender area code to recipient |
| Validity Period | `validity_period` | Discard undelivered messages after N seconds |
| Smart Encoding | `smart_encoding` | Convert unicode to GSM-7 |
| MMS Converter | `mms_converter` | Convert MMS to SMS if recipient can't receive MMS |
| Message Scheduling | `send_at` on message | Schedule sends up to 7 days ahead (see below) |
| Link Shortening | `shorten_urls` | Shorten links with branded domain + click tracking (see below) |

### List Services and Numbers

**Python**
```python
for service in client.messaging.v1.services.list():
    print(service.sid, service.friendly_name)

for number in client.messaging.v1.services(SERVICE_SID).phone_numbers.list():
    print(number.sid, number.phone_number)
```

**Node.js**
```node
const services = await client.messaging.v1.services.list();
services.forEach(s => console.log(s.sid, s.friendlyName));

const numbers = await client.messaging.v1.services(SERVICE_SID).phoneNumbers.list();
numbers.forEach(n => console.log(n.sid, n.phoneNumber));
```

---

## Production Messaging Features

The features below are platform capabilities that are configured on or require a Messaging Service. They are separate from the sender pool management above.

### Message Scheduling

Schedule messages 15 minutes to 35 days in advance. Requires `messagingServiceSid` (not `from`). Supports SMS, MMS, RCS, and WhatsApp. No additional cost — only charged for messages actually sent.

**Python**
```python
from datetime import datetime, timedelta, timezone

message = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Your appointment is tomorrow at 2pm.",
    send_at=(datetime.now(timezone.utc) + timedelta(hours=24)).isoformat(),
    schedule_type="fixed"
)
print(message.sid, message.status)  # SM..., scheduled
```

**Node.js**
```javascript
const sendAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
const message = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "+15558675310",
    body: "Your appointment is tomorrow at 2pm.",
    sendAt,
    scheduleType: "fixed",
});
```

Cancel a scheduled message before it sends:

```python
client.messages("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").update(status="canceled")
```

**Limitations:** Scheduled messages don't return a status callback event on creation. WhatsApp templates are validated at send time (not scheduling time) — non-compliant templates fail when `sendAt` fires. Opt-outs received after scheduling don't auto-cancel the message; cancel manually if needed.

---

### Compliance Toolkit (US SMS, Public Beta)

Automated compliance checks for US SMS. Enable in Console: Messaging > Settings > General > Enable Compliance Toolkit.

| Feature | What it does | Error code | Default |
|---------|-------------|-----------|---------|
| **Quiet Hours** | Reschedules non-essential messages sent during TCPA restricted hours (9PM–8AM recipient local time). Uses area code for timezone. 11 states have stricter windows. | 30610 (if block mode) | Enabled (reschedule mode) |
| **Reassigned Number Detection** | Checks FCC reassigned numbers database; re-checks every 30 days | 21610 | Enabled |
| **TCPA Known Litigators** | Blocks non-essential messages to known litigator numbers; re-verifies weekly | 30640 | **Not enabled by default** — requires account rep activation |
| **Opt-out Verification** | Blocks messages to users who replied STOP/UNSUBSCRIBE/END/QUIT/etc. | 21610 | Enabled |

**AI/ML classification:** Compliance Toolkit uses ML to classify messages as essential (OTP, alerts, support) vs non-essential (marketing, promotions). Essential messages bypass quiet hours and litigator checks. Override the classification with `messageIntent`:

**Python**
```python
message = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Your order shipped!",
    message_intent="confirm",    # Override ML: mark as essential/transactional
    risk_check="enable"          # Evaluate against all compliance checks
)
```

**Consent Management API** — Programmatically track opt-in/opt-out/re-opt-in status per phone number across SMS/MMS/RCS. Supports bulk upsert. Use alongside Compliance Toolkit to maintain consent records.

**Contact API** — Store recipient ZIP codes for more accurate quiet hours timezone inference (vs area code default).

---

### SMS Pumping Protection

Detects and blocks artificial inflation of SMS traffic (toll fraud where bad actors trigger high volumes of messages to premium-rate numbers they control).

**How it works:**
- Combines behavioral analysis with known fraud scheme identification using Twilio's proprietary model
- Analyzes: messages to regions