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.
To send a new outgoing message, make an HTTP POST to your Messages list resource URI:
The following parameters are required in your POST to send the message:
|From||A Twilio phone number 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.|
|To||The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format). For 'To' numbers without a '+', Twilio will use the same country code as the 'From' number. Twilio will also attempt to handle locally formatted numbers for that country code (e.g. (415) 555-1212 for US, 07400123456 for GB). If you are sending to a different country than the 'From' number, you must include a '+' and the country code to ensure proper delivery.|
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.
You must also POST at least one of the following parameters:
|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.
Note that if you do not specify a MediaUrl and the body is greater than 160 characters, the message will be sent as SMS, segmented and charged accordingly.
If you send a message with a MediaUrl to a recipient whose carrier does not support MMS, the message will be sent as an SMS with a shortened URL linking to your media (http://m.twil.io/ followed by 7 unique characters) appended to the end of the message body. The URL will remain active for 7 days. Messages sent in this way will be billed as SMS. If the appended URL causes the body of the text message to be greater than 160 characters, the message will be segmented and charged accordingly. Should you wish to disable this functionality, you can do so through the account settings page in the portal.
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.|
Each time a message status changes, Twilio will make an asynchronous HTTP request to the StatusCallback URL, if you provided one.
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 |
Send a Message from 415-814-1829 to 555-867-5309 begging Jenny for a second chance including a heart image:
You can queue as many messages as you like, however Twilio will only send out messages at a rate of one message per phone number per second. It is not possible to adjust this rate, and it does not vary based on the country in which your number is located.
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 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.