twilio-send-message

Overview

A single messages.create() call sends on any messaging channel — SMS, MMS, RCS, or WhatsApp. The channel is determined by the sender address and the recipient's capabilities. For channel selection guidance and the full onboarding sequence, see twilio-messaging-overview and twilio-messaging-channel-advisor.

For production: Send via messagingServiceSid instead of from. This enables sender pool management, RCS→SMS fallback, SMS pumping protection, link shortening, compliance toolkit, and scheduling. See twilio-messaging-services.

Key Patterns

Send with media (MMS, WhatsApp, RCS)

client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Here is your invoice.",
    media_url=["https://example.com/invoice.pdf"]
)

Supported: images (JPEG, PNG, GIF), PDF, audio, video. 5 MB max per attachment.

Send a template (WhatsApp required outside 24-hr window; RCS rich content)

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    content_sid="HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    content_variables='{"1": "Sarah", "2": "12345"}'
)

See twilio-content-template-builder for building templates.

Track delivery status

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Hello!",
    status_callback="https://yourapp.com/status"
)

Twilio POSTs at each state transition: queued → sent → delivered (or failed/undelivered).

Configure RCS→SMS fallback

Configured on the Messaging Service, not per-message. Add both an RCS sender and an SMS sender to the same Messaging Service. Twilio attempts RCS first and falls back to SMS on failure. See twilio-messaging-services and twilio-rcs-messaging.

CANNOT

• Cannot send cross-channel in a single API call. One messages.create() = one channel. For multi-channel fallback, use RCS→SMS via a Messaging Service, or implement sequencing in your app.
• Cannot send WhatsApp free-form outside the 24-hour service window. Use a pre-approved template (content_sid). See twilio-whatsapp-send-message.
• Cannot send MMS outside US/Canada. For international rich media, use WhatsApp or RCS.
• Cannot configure RCS→SMS fallback without a Messaging Service. Raw from sends don't support FallbackFrom.
• Cannot guarantee delivery on any channel. Always implement status callbacks.

Next Steps

• Pick a channel for your use case: twilio-messaging-channel-advisor
• Full messaging platform overview: twilio-messaging-overview
• Channel-specific deep dives: twilio-sms-send-message, twilio-rcs-messaging, twilio-whatsapp-send-message
• Sender pools, fallback, production features: twilio-messaging-services
• Build templates (cards, carousels, quick replies): twilio-content-template-builder
• Handle inbound messages and status callbacks: twilio-messaging-webhooks
• US A2P 10DLC compliance: twilio-compliance-onboarding
• OTP / verification use cases: twilio-verify-send-otp

Prerequisites

• Twilio account — New to Twilio? See twilio-account-setup
• Environment variables: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN — see twilio-iam-auth-setup
• SDK: pip install twilio / npm install twilio
• Channel-specific senders:
  • SMS/MMS: a Twilio phone number (see twilio-account-setup)
  • RCS: an RCS sender added to a Messaging Service (see twilio-rcs-messaging)
  • WhatsApp: an active WhatsApp sender (see twilio-whatsapp-send-message for sandbox, twilio-whatsapp-manage-senders for production)

Quickstart

Python

import os
from twilio.rest import Client

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

# SMS
sms = client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Your order has shipped."
)

# RCS — forces RCS only, no fallback
rcs = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="rcs:+15558675310",
    body="Your order has shipped."
)

# WhatsApp
whatsapp = client.messages.create(
    from_="whatsapp:+15017122661",
    to="whatsapp:+15558675310",
    body="Your order has shipped."
)

# Via Messaging Service (recommended — attempts RCS first, falls back to SMS)
msg = client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Your order has shipped."
)

Node.js

const client = require("twilio")(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

// SMS
const sms = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Your order has shipped.",
});

// RCS — forces RCS only, no fallback
const rcs = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "rcs:+15558675310",
    body: "Your order has shipped.",
});

// WhatsApp
const whatsapp = await client.messages.create({
    from: "whatsapp:+15017122661",
    to: "whatsapp:+15558675310",
    body: "Your order has shipped.",
});

// Via Messaging Service (attempts RCS first, falls back to SMS)
const msg = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "+15558675310",
    body: "Your order has shipped.",
});

Common Errors