Update to Twilio Developer Kit

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 231
    }
  ],
  "skill_md_contents": "---\nname: twilio-messaging-services\ndescription: >\n  Create and configure Twilio Messaging Services for production messaging.\n  Covers sender pools, geo-match, sticky sender, message scheduling,\n  compliance toolkit, SMS pumping protection, link shortening, and\n  intelligent alerts. Use this skill when setting up production-ready\n  messaging infrastructure.\n---\n\n## Overview\n\nA 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.\n\n**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`.\n\n---\n\n## Prerequisites\n\n- Twilio account with at least one SMS-capable phone number\n  — New to Twilio? See `twilio-account-setup`\n- Environment variables:\n  - `TWILIO_ACCOUNT_SID`\n  - `TWILIO_AUTH_TOKEN`\n  — See `twilio-iam-auth-setup` for credential setup and best practices\n- SDK: `pip install twilio` / `npm install twilio`\n\n---\n\n## Quickstart\n\n**Python**\n```python\nimport os\nfrom twilio.rest import Client\n\nclient = Client(os.environ[\"TWILIO_ACCOUNT_SID\"], os.environ[\"TWILIO_AUTH_TOKEN\"])\n\n# Step 1: Create the service\nservice = client.messaging.v1.services.create(\n    friendly_name=\"Production Notifications Service\"\n)\nprint(service.sid)  # MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx — save as MESSAGING_SERVICE_SID\n\n# Step 2: Add a phone number\nclient.messaging.v1 \\\n    .services(service.sid) \\\n    .phone_numbers \\\n    .create(phone_number_sid=\"PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\")\n\n# Step 3: Send via the service\nmessage = client.messages.create(\n    messaging_service_sid=service.sid,\n    to=\"+15558675310\",\n    body=\"Your order has shipped.\"\n)\nprint(message.sid)\n```\n\n**Node.js**\n```node\nconst twilio = require(\"twilio\");\nconst client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);\n\n// Step 1: Create the service\nconst service = await client.messaging.v1.services.create({\n    friendlyName: \"Production Notifications Service\",\n});\nconsole.log(service.sid);\n\n// Step 2: Add a phone number\nawait client.messaging.v1\n    .services(service.sid)\n    .phoneNumbers.create({ phoneNumberSid: \"PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" });\n\n// Step 3: Send via the service\nconst message = await client.messages.create({\n    messagingServiceSid: service.sid,\n    to: \"+15558675310\",\n    body: \"Your order has shipped.\",\n});\nconsole.log(message.sid);\n```\n\n---\n\n## Key Patterns\n\n### Create Service with Webhooks and Features\n\n**Python**\n```python\nservice = client.messaging.v1.services.create(\n    friendly_name=\"Marketing Campaigns\",\n    inbound_request_url=\"https://yourapp.com/sms/inbound\",\n    status_callback=\"https://yourapp.com/sms/status\",\n    sticky_sender=True,\n    area_code_geomatch=True,\n    validity_period=14400\n)\n```\n\n**Node.js**\n```node\nconst service = await client.messaging.v1.services.create({\n    friendlyName: \"Marketing Campaigns\",\n    inboundRequestUrl: \"https://yourapp.com/sms/inbound\",\n    statusCallback: \"https://yourapp.com/sms/status\",\n    stickySender: true,\n    areaCodeGeomatch: true,\n    validityPeriod: 14400,\n});\n```\n\n### Optional Features\n\n| Feature | Parameter | Description |\n|---------|-----------|-------------|\n| Sticky Sender | `sticky_sender` | Same sender for same recipient |\n| Area Code Geomatch | `area_code_geomatch` | Match sender area code to recipient |\n| Validity Period | `validity_period` | Discard undelivered messages after N seconds |\n| Smart Encoding | `smart_encoding` | Convert unicode to GSM-7 |\n| MMS Converter | `mms_converter` | Convert MMS to SMS if recipient can't receive MMS |\n| Message Scheduling | `send_at` on message | Schedule sends up to 7 days ahead (see below) |\n| Link Shortening | `shorten_urls` | Shorten links with branded domain + click tracking (see below) |\n\n### List Services and Numbers\n\n**Python**\n```python\nfor service in client.messaging.v1.services.list():\n    print(service.sid, service.friendly_name)\n\nfor number in client.messaging.v1.services(SERVICE_SID).phone_numbers.list():\n    print(number.sid, number.phone_number)\n```\n\n**Node.js**\n```node\nconst services = await client.messaging.v1.services.list();\nservices.forEach(s => console.log(s.sid, s.friendlyName));\n\nconst numbers = await client.messaging.v1.services(SERVICE_SID).phoneNumbers.list();\nnumbers.forEach(n => console.log(n.sid, n.phoneNumber));\n```\n\n---\n\n## Production Messaging Features\n\nThe features below are platform capabilities that are configured on or require a Messaging Service. They are separate from the sender pool management above.\n\n### Message Scheduling\n\nSchedule 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.\n\n**Python**\n```python\nfrom datetime import datetime, timedelta, timezone\n\nmessage = client.messages.create(\n    messaging_service_sid=\"MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n    to=\"+15558675310\",\n    body=\"Your appointment is tomorrow at 2pm.\",\n    send_at=(datetime.now(timezone.utc) + timedelta(hours=24)).isoformat(),\n    schedule_type=\"fixed\"\n)\nprint(message.sid, message.status)  # SM..., scheduled\n```\n\n**Node.js**\n```javascript\nconst sendAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();\nconst message = await client.messages.create({\n    messagingServiceSid: \"MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n    to: \"+15558675310\",\n    body: \"Your appointment is tomorrow at 2pm.\",\n    sendAt,\n    scheduleType: \"fixed\",\n});\n```\n\nCancel a scheduled message before it sends:\n\n```python\nclient.messages(\"SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\").update(status=\"canceled\")\n```\n\n**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.\n\n---\n\n### Compliance Toolkit (US SMS, Public Beta)\n\nAutomated compliance checks for US SMS. Enable in Console: Messaging > Settings > General > Enable Compliance Toolkit.\n\n| Feature | What it does | Error code | Default |\n|---------|-------------|-----------|---------|\n| **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) |\n| **Reassigned Number Detection** | Checks FCC reassigned numbers database; re-checks every 30 days | 21610 | Enabled |\n| **TCPA Known Litigators** | Blocks non-essential messages to known litigator numbers; re-verifies weekly | 30640 | **Not enabled by default** — requires account rep activation |\n| **Opt-out Verification** | Blocks messages to users who replied STOP/UNSUBSCRIBE/END/QUIT/etc. | 21610 | Enabled |\n\n**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`:\n\n**Python**\n```python\nmessage = client.messages.create(\n    messaging_service_sid=\"MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n    to=\"+15558675310\",\n    body=\"Your order shipped!\",\n    message_intent=\"confirm\",    # Override ML: mark as essential/transactional\n    risk_check=\"enable\"          # Evaluate against all compliance checks\n)\n```\n\n**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.\n\n**Contact API** — Store recipient ZIP codes for more accurate quiet hours timezone inference (vs area code default).\n\n---\n\n### SMS Pumping Protection\n\nDetects and blocks artificial inflation of SMS traffic (toll fraud where bad actors trigger high volumes of messages to premium-rate numbers they control).\n\n**How it works:**\n- Combines behavioral analysis with known fraud scheme identification using Twilio's proprietary model\n- Analyzes: messages to regions known for pumping, countries with no prior sending history, patterns suggesting non-human behavior\n- Auto-blocks suspected pumping destinations — returns error **30450**\n- Enable in Console: Messaging > Settings > General > SMS Pumping Protection\n- **Free in US/Canada**; other regions check SMS Pricing page\n\n**Per-message risk check:**\n\n**Python**\n```python\nmessage = client.messages.create(\n    messaging_service_sid=\"MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n    to=\"+15558675310\",\n    body=\"Your verification code is 123456.\",\n    risk_check=\"enable\"   # Assess pumping risk for this specific message\n)\n```\n\n**`riskCheck` parameter values:**\n- `enable` (default for OTP/2FA messages): Apply SMS pumping protection\n- `disable`: Skip protection (use for marketing messages where false positives are costly)\n\n**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.\n\n**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.\n\n**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.\n\n---\n\n### Link Shortening & Click Tracking\n\nAutomatically shorten URLs in message bodies using a branded domain, with click tracking.\n\n**Setup:**\n1. Configure a branded short domain in Console (e.g., `link.yourcompany.com`)\n2. Add DNS records as directed\n3. Enable `ShortenUrls: true` on your Messaging Service\n\n**Python**\n```python\nservice = client.messaging.v1.services(\"MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\").update(\n    shorten_urls=True\n)\n```\n\nOnce enabled, any URL in the message body is auto-shortened to your branded domain. Click events are delivered via status callback.\n\n- Links are retained for **90 days** after creation\n- Click tracking events appear in status callbacks alongside delivery events\n\n---\n\n### Intelligent Alerts\n\nML-based monitoring that detects unusual error patterns and alerts you before they become outages. This is an account-level feature (not per-service).\n\n**Monitors 5 error codes:**\n- 30001 (Queue overflow), 30005 (Unknown destination), 30006 (Landline or unreachable), 30007 (Carrier violation / spam filter), 30008 (Unknown error)\n\n**How it works:**\n- Analyzes error patterns in 5-minute windows\n- Calculates impact score based on error volume and velocity\n- Classifies: **Urgent** (>0.80), **Important** (0.40–0.80), **Warning** (<0.40)\n- Alerts via email or webhook\n\n**Free feature** — enable in Console > Messaging > Settings > Intelligent Alerts.\n\n---\n\n## CANNOT\n\n- **Cannot add a phone number to multiple Messaging Services** — A number belongs to one service at a time\n- **Cannot determine throughput from the API** — Throughput depends on number type (long code, short code, toll-free) and is not exposed programmatically\n- **Cannot schedule messages without a Messaging Service** — `sendAt` requires `messagingServiceSid`, not `from`. Must also set `schedule_type=\"fixed\"`\n- **Cannot schedule more than 35 days ahead** — Scheduling window is 15 minutes to 35 days\n- **Cannot use compliance toolkit outside the US** — Currently US SMS only, public beta\n- **Cannot use compliance toolkit without a Messaging Service** — Features are configured per service\n- **Cannot customize SMS pumping ML thresholds** — Auto-blocking sensitivity is not configurable; use Global Safe List to whitelist known-good prefixes\n- **Cannot use link shortening without a branded domain** — Must configure a custom short domain first; no default short domain provided\n- **Cannot use link shortening for WhatsApp** — Only available for SMS/MMS\n- **Cannot customize intelligent alerts error code list** — Fixed to the 5 monitored error codes\n- **Messaging Services are required for US A2P 10DLC** — Campaign registration attaches to a Messaging Service\n- **Inbound routing is per-service, not per-number** — All inbound messages to numbers in the service go to `inbound_request_url`\n\n---\n\n## Next Steps\n\n- **Channel overview and onboarding guide:** `twilio-messaging-overview`\n- **US compliance for A2P traffic:** `twilio-compliance-onboarding`\n- **Send SMS:** `twilio-sms-send-message`\n- **Handle inbound SMS:** `twilio-messaging-webhooks`\n"
}