openai/twilio-messaging-services

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

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

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

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

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

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

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

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

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:

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

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 known for pumping, countries with no prior sending history, patterns suggesting non-human behavior
• Auto-blocks suspected pumping destinations — returns error 30450
• Enable in Console: Messaging > Settings > General > SMS Pumping Protection
• Free in US/Canada; other regions check SMS Pricing page

Per-message risk check:

Python

message = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Your verification code is 123456.",
    risk_check="enable"   # Assess pumping risk for this specific message
)

riskCheck parameter values:

• enable (default for OTP/2FA messages): Apply SMS pumping protection
• disable: Skip protection (use for marketing messages where false positives are costly)

Global Safe List API — Whitelist phone numbers that bypass SMS Pumping Protection, Verify Fraud Guard, and other risk checks. Use for known-good customers and approved recipients.

False positives: The ML model may occasionally flag legitimate users. If this happens: add to Global Safe List, switch to WhatsApp/Messenger for those recipients, or contact Twilio Support.

Note: This is separate from Verify Fraud Guard, which only protects Verify API sends. SMS Pumping Protection covers all Programmable Messaging sends through a Messaging Service.

---

Link Shortening & Click Tracking

Automatically shorten URLs in message bodies using a branded domain, with click tracking.

Setup:

1. Configure a branded short domain in Console (e.g., link.yourcompany.com)
2. Add DNS records as directed
3. Enable ShortenUrls: true on your Messaging Service

Python

service = client.messaging.v1.services("MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").update(
    shorten_urls=True
)

Once enabled, any URL in the message body is auto-shortened to your branded domain. Click events are delivered via status callback.

• Links are retained for 90 days after creation
• Click tracking events appear in status callbacks alongside delivery events

---

Intelligent Alerts

ML-based monitoring that detects unusual error patterns and alerts you before they become outages. This is an account-level feature (not per-service).

Monitors 5 error codes:

• 30001 (Queue overflow), 30005 (Unknown destination), 30006 (Landline or unreachable), 30007 (Carrier violation / spam filter), 30008 (Unknown error)

How it works:

• Analyzes error patterns in 5-minute windows
• Calculates impact score based on error volume and velocity
• Classifies: Urgent (>0.80), Important (0.40–0.80), Warning (<0.40)
• Alerts via email or webhook

Free feature — enable in Console > Messaging > Settings > Intelligent Alerts.

---

CANNOT

• Cannot add a phone number to multiple Messaging Services — A number belongs to one service at a time
• Cannot determine throughput from the API — Throughput depends on number type (long code, short code, toll-free) and is not exposed programmatically
• Cannot schedule messages without a Messaging Service — sendAt requires messagingServiceSid, not from. Must also set schedule_type="fixed"
• Cannot schedule more than 35 days ahead — Scheduling window is 15 minutes to 35 days
• Cannot use compliance toolkit outside the US — Currently US SMS only, public beta
• Cannot use compliance toolkit without a Messaging Service — Features are configured per service
• Cannot customize SMS pumping ML thresholds — Auto-blocking sensitivity is not configurable; use Global Safe List to whitelist known-good prefixes
• Cannot use link shortening without a branded domain — Must configure a custom short domain first; no default short domain provided
• Cannot use link shortening for WhatsApp — Only available for SMS/MMS
• Cannot customize intelligent alerts error code list — Fixed to the 5 monitored error codes
• Messaging Services are required for US A2P 10DLC — Campaign registration attaches to a Messaging Service
• Inbound routing is per-service, not per-number — All inbound messages to numbers in the service go to inbound_request_url

---

Next Steps

• Channel overview and onboarding guide: twilio-messaging-overview
• US compliance for A2P traffic: twilio-compliance-onboarding
• Send SMS: twilio-sms-send-message
• Handle inbound SMS: twilio-messaging-webhooks