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#

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.

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