Sending an SMS or MMS is one of the most common tasks performed on the Twilio Platform. Sending a message is as simple as POST-ing to the Messages resource, but since it’s a common action it’s worth walking through in detail below.
Send a message from 415-814-1829 to 651-867-5309 wishing your friend Jenny good luck on the bar exam, along with an image of a hamster eating a four-leaf clover. Note that while you can send text-only messages just about anywhere on the planet, sending images is currently only possible in the US and Canada:
To send a new outgoing message, make an HTTP POST to your Messages list resource URI:
To parameter is required in your POST to send the
|To||The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format).|
You must POST at least one of the following parameters to determine the 'From' phone number or Sender ID of your message:
|From||A Twilio phone number (in E.164 format) or alphanumeric sender ID enabled for the type of message you wish to send. Phone numbers or short codes purchased from Twilio work here. You cannot (for example) spoof messages from your own cell phone number.|
|MessagingServiceSid||The 34 character unique id of the Messaging Service you want to associate with this Message. Set this parameter to use the Messaging Service Settings and Copilot Features you have configured. When only this parameter is set, Twilio will use your enabled Copilot Features to select the From phone number for delivery.|
There is a slight difference in API response when specifying the
MessagingServiceSid parameter. When you only specify the
From parameter, Twilio will validate the phone numbers synchronously and return either a
queued status or an error. When specifying the
MessagingServiceSid parameter, Twilio will first return an
accepted status. Twilio then determines the optimal From phone number and any delivery errors will be sent asynchronously to your StatusCallback URL.
You must also POST at least one of the following parameters for the content of your message:
|Body||The text of the message you want to send, limited to 1600 characters.|
|MediaUrl||The URL of the media you wish to send out with the message. |
If you are sending non-BMP characters in the message Body the number of characters could be smaller than 1600. Almost all global languages are supported without the use of the non-BMP character plane.
Content types for MediaUrl validation are fetched via the content-type header at the provided URLs. If the content-type header does not match the media, Twilio will reject the request. Twilio supports image/gif, image/png, and image/jpeg mime-types and accepts many others.
You may include the following parameters:
|StatusCallback||A URL that Twilio will POST to each time your message status changes to one of the following: |
|ApplicationSid||Twilio will POST |
|MaxPrice||The total maximum price up to the fourth decimal (0.0001) in US dollars acceptable for the message to be delivered. All messages regardless of the price point will be queued for delivery. A POST request will later be made to your Status Callback URL with a status change of 'Sent' or 'Failed'. When the price of the message is above this value the message will fail and not be sent. When MaxPrice is not set, all prices for the message is accepted. This parameter is not available when sending with a Messaging Service.|
The parameters Twilio passes to your application in its request to the StatusCallback URL include all the standard request parameters and these additional parameters:
|MessageStatus||The status of the message. Message delivery information is reflected in message status. The possible values are described here.|
|ErrorCode||The error code (if any) associated with your message. If your message status is |
As you use Twilio Messaging to power different use cases, it may be helpful to organize your account and message logs into separate Messaging Services. Messaging Services allow you to organize your messages and enable specific features for these groups of messages. This keeps your code clean and lets you adjust messaging configuration right from your Account Portal.
With every Messaging Service, you start by configuring the Inbound Request URL and Status Callback URL. For advanced configuration, Twilio Copilot Features are available to add intelligence to your application.
When sending messages, you must associate one or more phone numbers and/or short codes to your Messaging Service. One of the phone numbers in your Messaging Service will be chosen based on the enabled Copilot Features whenever you send an outbound message.
Alphanumeric sender IDs are used for branded one-way messaging. Alphanumeric sender IDs may be used at no additional cost when sending an SMS to countries that are supported. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: [A-Za-z0-9 ]. When using an alphanumeric sender ID, at least 1 letter and no more than 11 alphanumeric characters may be used.
Your messages may be rate limited at different rates based on the destination you're sending messages to. For example, for US/CA destinations the limit is one message per second. Internationally, the upper limit is 10 MPS. For more information, check out this FAQ.
If you anticipate the need to send out a large number of messages quickly (a time-limited promotion, for example) or at a rate greater than one message per second, you can also purchase additional numbers, increasing your outbound capacity.
Short codes are not subject to the same rate limits as long-code numbers and may be a better option for you. Check out our short code FAQ to determine what is best for you.
By specifying an Message URL for your messaging enabled Twilio phone number, Twilio will make a request to your application to notify you when someone replies to a message you send. Twilio's request and your corresponding response are covered in the Message portion of the TwiML documentation.