twilio-messaging-services
GitHub用于创建和配置 Twilio Messaging Service，支持发送者池、地理匹配、粘性发送者、消息调度及合规防护。适用于构建生产级短信基础设施，提供 Python/Node.js 快速入门与关键模式示例。
Trigger Scenarios
Install
npx skills add fanfan-de/anybox --skill twilio-messaging-services -g -y
SKILL.md
Frontmatter
{
"name": "twilio-messaging-services",
"description": "Create and configure Twilio Messaging Services for production messaging. Covers sender pools, geo-match, sticky sender, message scheduling, compliance toolkit, SMS pumping protection, link shortening, and intelligent alerts. Use this skill when setting up production-ready messaging infrastructure."
}
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_SIDTWILIO_AUTH_TOKEN— Seetwilio-iam-auth-setupfor 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 protectiondisable: 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:
- Configure a branded short domain in Console (e.g.,
link.yourcompany.com) - Add DNS records as directed
- Enable
ShortenUrls: trueon 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 —
sendAtrequiresmessagingServiceSid, notfrom. Must also setschedule_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
Version History
- 08dc189 Current 2026-07-05 19:09
