Message Resource
A Message resource represents an inbound or outbound message. Twilio creates a Message when any of the following occur:
- You create a Message resource (i.e., send an outbound message) via the REST API
- Twilio executes a <Message> TwiML instruction
- Someone sends a message to one of your Twilio numbers or messaging channel addresses
With the Message resource, you can:
- Create new messages (i.e., send outbound messages)
- Fetch a specific message
- Read a list of messages
- Update or redact the content of an existing message
- Delete messages from your account
If you're using Messaging Services, you can also use the Message resource to:
A Message resource can also have a Media sub-resource and/or a MessageFeedback sub-resource.
For step-by-step instructions for sending your first SMS with Twilio, check out one of the SMS quickstarts.
Looking to send WhatsApp messages with Twilio? Try one of the WhatsApp quickstarts.
If you're looking for how to respond to incoming messages, check out the How to Receive and Reply to SMS Messages tutorial.
Message properties
Resource Properties in REST API format | |
---|---|
body
|
The text content of the message |
num_segments
|
The number of segments that make up the complete message. SMS message bodies that exceed the character limit are segmented and charged as multiple messages. Note: For messages sent via a Messaging Service, |
direction
|
The direction of the message. Can be: |
from
|
The sender's phone number (in E.164 format), alphanumeric sender ID, Wireless SIM, short code, or channel address (e.g., |
to
|
The recipient's phone number (in E.164 format) or channel address (e.g. |
date_updated
|
The RFC 2822 timestamp (in GMT) of when the Message resource was last updated |
price
|
The amount billed for the message in the currency specified by |
error_message
|
The description of the |
uri
|
The URI of the Message resource, relative to |
account_sid
|
The SID of the Account associated with the Message resource |
num_media
|
The number of media files associated with the Message resource. |
status
|
The status of the Message. Possible values: |
messaging_service_sid
|
The SID of the Messaging Service associated with the Message resource. The value is |
sid
|
The unique, Twilio-provided string that identifies the Message resource. |
date_sent
|
The RFC 2822 timestamp (in GMT) of when the Message was sent. For an outgoing message, this is when Twilio sent the message. For an incoming message, this is when Twilio sent the HTTP request to your incoming message webhook URL. |
date_created
|
The RFC 2822 timestamp (in GMT) of when the Message resource was created |
error_code
|
The error code returned if the Message |
price_unit
|
The currency in which |
api_version
|
The API version used to process the Message |
subresource_uris
|
A list of related resources identified by their URIs relative to |
Message Status values
The table below lists possible values of a Message resource's Status
. As messages can be either outbound or inbound, each status description explicitly indicates to which message direction the status applies.
ENUM:STATUS possible values in REST API format | |
---|---|
queued
|
The API request to send an outbound message was successful and the message is queued to be sent out by a specific |
sending
|
Twilio is in the process of dispatching the outbound message to the nearest upstream carrier in the network. |
sent
|
The nearest upstream carrier accepted the outbound message. |
failed
|
The outbound message failed to send. This can happen for various reasons including queue overflows, Account suspensions and media errors. Twilio does not charge you for failed messages. |
delivered
|
Twilio has received confirmation of outbound message delivery from the upstream carrier, and, where available, the destination handset. |
undelivered
|
Twilio received a delivery receipt indicating that the outbound message was not delivered. This can happen for many reasons including carrier content filtering and the availability of the destination handset. |
receiving
|
The inbound message was received by Twilio and is currently being processed. |
received
|
The inbound message was received and processing is complete. |
accepted
|
[Messaging Service only] Twilio has received your API request to immediatedly send an outbound message with a Messaging Service. If you did not provide a specific |
scheduled
|
[Messaging Service only] The Message resource is scheduled to be sent with a Messaging Service. If you schedule a message with a Messaging Service, this is the initial |
read
|
WhatsApp only: The recipient opened the outbound message. Recipient must have read receipts enabled. |
partially_delivered
|
[Deprecated] |
canceled
|
[Messaging Service only] The message scheduled with a Messaging Service has been canceled. |
NumSegments property
The NumSegments
property is relevant for SMS messages only.
For outbound SMS messages, this property indicates the number of SMS messages it took to deliver the body of the message.
If the body of a message is more than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio segments and annotates your messages to attempt proper reassembly on the recipient's handset (not supported by all carriers and handsets). This ensures your body text transmits with the highest fidelity.
On inbound SMS messages, this property indicates the number of SMS messages that make up the message received.
If the body of a message is more than 160 GSM-7 characters (or 70 UCS-2 characters), Twilio attempts to reassemble the message received by your Twilio phone number. All carriers and handsets do not necessarily support this.
Your account is charged for each segment sent or received.
Learn more on the SMS Character Limit Glossary page.
Create a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
To send a new outgoing message, send an HTTP POST request to your Account's Messages list resource URI.
If you want to send messages while in trial mode, you must first verify your 'To' phone number with Twilio. You can verify your phone number by adding it to your Verified Caller IDs in the Console.
Twilio queues messages for delivery at your prescribed rate limit. API requests for messages that exceed the specified rates will be queued and executed as capacity is available.
If you need to enqueue a large number of messages, you may want to use Messaging Services.
Every request to create a new Message resource requires a recipient, a sender, and content.
A recipient is specified via the To
parameter.
The sender is specified via one of the following parameters:
From
MessagingServiceSid
The message content is specified via one of the following parameters:
MediaUrl
Body
ContentSid
The table below describes these parameters in more detail.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account creating the Message resource. |
to
Required
|
The recipient's phone number in E.164 format (for SMS/MMS) or channel address, e.g. |
status_callback
Optional
|
The URL of the endpoint to which Twilio sends Message status callback requests. URL must contain a valid hostname and underscores are not allowed. If you include this parameter with the |
application_sid
Optional
|
The SID of the associated TwiML Application. If this parameter is provided, the |
max_price
Optional
|
The maximum price in US dollars that you are willing to pay for this Message's delivery. The value can have up to four decimal places. When the |
provide_feedback
Optional
|
Boolean indicating whether or not you intend to provide delivery confirmation feedback to Twilio (used in conjunction with the Message Feedback subresource). Default value is |
attempt
Optional
|
Total number of attempts made (including this request) to send the message regardless of the provider used |
validity_period
Optional
|
The maximum length in seconds that the Message can remain in Twilio's outgoing message queue. If a queued Message exceeds the |
force_delivery
Optional
|
Reserved |
content_retention
Optional
|
Determines if the message content can be stored or redacted based on privacy settings |
address_retention
Optional
|
Determines if the address can be stored or obfuscated based on privacy settings |
smart_encoded
Optional
|
Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: |
persistent_action
Optional
|
Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages. |
shorten_urls
Optional
|
For Messaging Services with Link Shortening configured only: A Boolean indicating whether or not Twilio should shorten links in the |
schedule_type
Optional
|
For Messaging Services only: Include this parameter with a value of |
send_at
Optional
|
The time that Twilio will send the message. Must be in ISO 8601 format. |
send_as_mms
Optional
|
If set to |
content_variables
Optional
|
For Content Editor/API only: Key-value pairs of Template variables and their substitution values. |
risk_check
Optional
|
For SMS pumping protection feature only: Include this parameter with a value of |
from
Required if
messaging_service_sid
is not passed
|
The sender's Twilio phone number (in E.164 format), alphanumeric sender ID, Wireless SIM, short code, or channel address (e.g., |
messaging_service_sid
Required if
from
is not passed
|
The SID of the Messaging Service you want to associate with the Message. When this parameter is provided and the |
body
Required if
media_url,
content_sid
is not passed
|
The text content of the outgoing message. Can be up to 1,600 characters in length. SMS only: If the |
media_url
Required if
body,
content_sid
is not passed
|
The URL of media to include in the Message content. |
content_sid
Required if
body,
media_url
is not passed
|
For Content Editor/API only: The SID of the Content Template to be used with the Message, e.g., |
Twilio's request to the StatusCallback URL
Whenever a Message resource's Status
changes, Twilio sends a POST request to the Message resource's StatusCallback
URL.
In a status callback request, Twilio provides a subset of the standard request properties, and additionally MessageStatus
and ErrorCode
. These properties are described in the table below.
Property | Description |
MessageStatus |
The status of the Message resource at the time the status callback request was sent. |
ErrorCode |
If an error occurred (i.e. the MessageStatus is failed or undelivered ), this property provides additional information about the failure. |
The properties included in Twilio's request to the StatusCallback URL vary by messaging channel and event type and are subject to change.
Twilio occasionally adds new properties without advance notice.
When integrating with status callback requests, it is important that your implementation is able to accept and correctly run signature validation on an evolving set of parameters.
Twilio strongly recommends using the signature validation methods provided in the Helper Libraries and not implementing your own signature validation.
SMS/MMS
For most SMS/MMS Messages that have a Status
of delivered
or undelivered
, Twilio's request to the StatusCallback
URL contains an additional property:
Property | Description |
RawDlrDoneDate |
This property is a passthrough of the Done Date included in the DLR (Delivery Receipt) that Twilio received from the carrier. The value is in
|
WhatsApp and other messaging channels
If the Message resource uses WhatsApp or another messaging channel, Twilio's request to the StatusCallback
URL contains additional properties. These properties are listed in the table below.
Property | Description |
ChannelInstallSid |
The Installed Channel SID that was used to send this message |
ChannelStatusMessage |
The error message returned by the underlying messaging channel if Message delivery failed. This property is present only if the Message delivery failed. |
ChannelPrefix |
The channel-specific prefix identifying the messaging channel associated with this Message |
EventType |
This property contains information about post-delivery events. If the channel supports read receipts (currently WhatsApp only), this property's value is |
Send an SMS message
The example below shows how to create a Message resource with an SMS recipient.
Sending this POST request causes Twilio to send a text message from +15557122661
(a Twilio phone number belonging to the Account sending the request) to +15558675310
. The content of the text message is Hi there
.
Example 1
Send a WhatsApp message
If you have a Twilio-approved WhatsApp sender, you can send WhatsApp messages by creating a new Message resource. (WhatsApp session limitations apply.)
The From
parameter value must be your approved WhatsApp sender address (e.g., whatsapp:+15552221111
).
The To
parameter value must be a WhatsApp recipient address (e.g., whatsapp:+15553334444
).
You must also provide message content via the Body
and/or MediaUrl
parameters.
If you're using Messaging Services with Content API/Content Editor, you can provide message content via the contentSid
and contentVariables
parameters.
Note: WhatsApp does not support including a text body in the same message as a video, audio file, document, contact (vCard), or location. If you pass the Body
parameter on a message with one of these media types, the body is ignored and not delivered to the recipient.
Example 2
Send a message with a Messaging Service
When sending a message with a Messaging Service, you must provide a recipient via the To
parameter and content via the Body
, ContentSid
, or MediaUrl
parameters. In addition, you must provide the MessagingServiceSid
.
If you provide a MessagingServiceSid
and no From
parameter, Twilio determines the optimal From
value from your Sender Pool. In this case, the Message resource's initial Status
value is accepted
.
Optionally, you can provide a MessagingServiceSid
and a From
parameter. The From
parameter must be a sender from your Messaging Service's Sender Pool. In this case, the Message resource's initial Status
value is queued
.
With Messaging Services, you can also schedule messages to be sent in the future and send messages with shortened links.
Example 3
Fetch a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
Returns a single Message resource specified by the provided Message SID
.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account associated with the Message resource |
sid
Path
|
The SID of the Message resource to be fetched |
Example 1
Read multiple Message resources
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
Read multiple Message resources by sending a GET request to your Account's Messages list URI.
Results are sorted by the DateSent
field, with the most recent messages appearing first.
If you are using the Twilio REST API and plan on requesting more records than will fit on a single page, you may want to use the response's nextpageuri property. Requesting this URI ensures that your next request picks up where it left off and can prevent you from retrieving duplicate data if you are actively sending or receiving messages.
This is not necessary if you are using one of the Helper Libraries, which automatically handle pagination. Take a look at the Helper Library documentation for more information.
You can also filter the Messages list by providing the following query string parameters to the listing resource:
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account associated with the Message resources. |
to
Optional
|
Filter by recipient. For example: Set this |
from
Optional
|
Filter by sender. For example: Set this |
date_sent
Optional
|
Filter by Message |
Example 1
Example 2
Example 3
Example 4
Update a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
Updates the body of a Message resource. Send a POST request to a Message resource's URI containing the updated parameters.
This action is primarily used to redact Message content. To redact a Message resources's Body
, send a POST request to the Message resource's URI and set the Body
parameter as an empty string: ""
. This redacts the Body
of a message while keeping the other Message resource properties intact.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account that created the Message resources to update. |
sid
Path
|
The SID of the Message resource to be updated |
body
Optional
|
The new |
status
Optional
|
Set as |
Example 1
Delete a Message resource
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json
To delete a Message resource, send a DELETE request to the Message resource's URI.
If the DELETE request is successful, Twilio's response status code is HTTP 204 (No Content)
.
A deleted Message resource no longer appears in your Account's Messaging logs. Deleted messages cannot be recovered.
Deleting a Message resource also deletes any associated Media and/or MessageFeedback sub-resources. Any associated media file is also deleted unless the same media file is associated with another Message resource in your Account. For example, if you send 1,000 messages with the same media file (e.g., a .jpeg
file), that media file remains accessible until all 1,000 associated Message resources (and/or the associated Media sub-resources) are deleted.
Message bodies may persist for up to 30 days after an HTTP DELETE request in our database backups.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account associated with the Message resource |
sid
Path
|
The SID of the Message resource you wish to delete |
Example 1
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.