Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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:

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.

(information)

Info

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

message-properties page anchor
Resource properties
bodytype: stringPII MTL: 30 days

The text content of the message


num_segmentstype: stringNot PII

The number of segments that make up the complete message. SMS message bodies that exceed the character limit(link takes you to an external page) are segmented and charged as multiple messages. Note: For messages sent via a Messaging Service, num_segments is initially 0, since a sender hasn't yet been assigned.


directiontype: enum<STRING>Not PII

The direction of the message. Can be: inbound for incoming messages, outbound-api for messages created by the REST API, outbound-call for messages created during a call, or outbound-reply for messages created in response to an incoming message.

Possible values:
inboundoutbound-apioutbound-calloutbound-reply

fromtype: string<PHONE NUMBER>PII MTL: 120 days

The sender's phone number (in E.164(link takes you to an external page) format), alphanumeric sender ID(link takes you to an external page), Wireless SIM(link takes you to an external page), short code(link takes you to an external page), or channel address(link takes you to an external page) (e.g., whatsapp:+15554449999). For incoming messages, this is the number or channel address of the sender. For outgoing messages, this value is a Twilio phone number, alphanumeric sender ID, short code, or channel address from which the message is sent.


totype: stringPII MTL: 120 days

The recipient's phone number (in E.164(link takes you to an external page) format) or channel address(link takes you to an external page) (e.g. whatsapp:+15552229999)


date_updatedtype: string<DATE TIME RFC 2822>Not PII

The RFC 2822(link takes you to an external page) timestamp (in GMT) of when the Message resource was last updated


pricetype: stringNot PII

The amount billed for the message in the currency specified by price_unit. The price is populated after the message has been sent/received, and may not be immediately availalble. View the Pricing page(link takes you to an external page) for more details.


error_messagetype: stringNot PII

The description of the error_code if the Message status is failed or undelivered. If no error was encountered, the value is null.


uritype: stringNot PII

The URI of the Message resource, relative to https://api.twilio.com.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) associated with the Message resource


num_mediatype: stringNot PII

The number of media files associated with the Message resource.


statustype: enum<STRING>Not PII

The status of the Message. Possible values: accepted, scheduled, canceled, queued, sending, sent, failed, delivered, undelivered, receiving, received, or read (WhatsApp only). For more information, See detailed descriptions(link takes you to an external page).


messaging_service_sidtype: SID<MG>Not PII

The SID of the Messaging Service(link takes you to an external page) associated with the Message resource. The value is null if a Messaging Service was not used.


sidtype: SID<SM|MM>Not PII

The unique, Twilio-provided string that identifies the Message resource.


date_senttype: string<DATE TIME RFC 2822>Not PII

The RFC 2822(link takes you to an external page) 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_createdtype: string<DATE TIME RFC 2822>Not PII

The RFC 2822(link takes you to an external page) timestamp (in GMT) of when the Message resource was created


error_codetype: integerNot PII

The error code(link takes you to an external page) returned if the Message status is failed or undelivered. If no error was encountered, the value is null.


price_unittype: string<CURRENCY>Not PII

The currency in which price is measured, in ISO 4127(link takes you to an external page) format (e.g. usd, eur, jpy).


api_versiontype: stringNot PII

The API version used to process the Message


subresource_uristype: object<URI MAP>Not PII

A list of related resources identified by their URIs relative to https://api.twilio.com


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 From sender. For messages sent without a Messaging Service this is the initial Status value of the Message resource.
'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 From sender in the service's Sender Pool to use, the service is dynamically selecting a From sender. For unscheduled messages to be sent with a Messaging Service, this is the initial Status value of the Message resource.
'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 Status value of the Message resource.
'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.

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

create-a-message-resource page anchor
POST 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.

(warning)

Warning

If you want to send messages while in trial mode, you must first verify your 'To' phone number with Twilio(link takes you to an external page). You can verify your phone number by adding it to your Verified Caller IDs(link takes you to an external page) in the Console.

(warning)

Warning

Twilio queues messages for delivery at your prescribed rate limit(link takes you to an external page). API requests for messages that exceed the specified rates(link takes you to an external page) 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

create-parameters page anchor
URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) creating the Message resource.


Request body parameters
Totype: string<PHONE NUMBER>PII MTL: 120 days
Required

The recipient's phone number in E.164(link takes you to an external page) format (for SMS/MMS) or channel address(link takes you to an external page), e.g. whatsapp:+15552229999.


StatusCallbacktype: string<URI>Not PII

The URL of the endpoint to which Twilio sends Message status callback requests(link takes you to an external page). URL must contain a valid hostname and underscores are not allowed. If you include this parameter with the messaging_service_sid, Twilio uses this URL instead of the Status Callback URL of the Messaging Service(link takes you to an external page).


ApplicationSidtype: SID<AP>Not PII

The SID of the associated TwiML Application(link takes you to an external page). Message status callback requests(link takes you to an external page) are sent to the TwiML App's message_status_callback URL. Note that the status_callback parameter of a request takes priority over the application_sid parameter; if both are included application_sid is ignored.


MaxPricetype: numberNot PII

[DEPRECATED] This parameter will no longer have any effect as of 2024-06-03.


ProvideFeedbacktype: booleanNot PII

Boolean indicating whether or not you intend to provide delivery confirmation feedback to Twilio (used in conjunction with the Message Feedback subresource(link takes you to an external page)). Default value is false.


Attempttype: integerNot PII

Total number of attempts made (including this request) to send the message regardless of the provider used


ValidityPeriodtype: integerNot PII

The maximum length in seconds that the Message can remain in Twilio's outgoing message queue. If a queued Message exceeds the validity_period, the Message is not sent. Accepted values are integers from 1 to 14400. Default value is 14400. A validity_period greater than 5 is recommended. Learn more about the validity period(link takes you to an external page)


ForceDeliverytype: booleanNot PII

Reserved


ContentRetentiontype: enum<STRING>Not PII

Determines if the message content can be stored or redacted based on privacy settings

Possible values:
retaindiscard

AddressRetentiontype: enum<STRING>Not PII

Determines if the address can be stored or obfuscated based on privacy settings

Possible values:
retainobfuscate

SmartEncodedtype: booleanNot PII

Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.


PersistentActiontype: string[]Not PII

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages(link takes you to an external page).


ShortenUrlstype: booleanNot PII

For Messaging Services with Link Shortening configured(link takes you to an external page) only: A Boolean indicating whether or not Twilio should shorten links in the body of the Message. Default value is false. If true, the messaging_service_sid parameter must also be provided.


ScheduleTypetype: enum<STRING>Not PII

For Messaging Services only: Include this parameter with a value of fixed in conjuction with the send_time parameter in order to schedule a Message(link takes you to an external page).

Possible values:
fixed

SendAttype: string<DATE TIME>Not PII

The time that Twilio will send the message. Must be in ISO 8601 format.


SendAsMmstype: booleanNot PII

If set to true, Twilio delivers the message as a single MMS message, regardless of the presence of media.


ContentVariablestype: stringNot PII

For Content Editor/API(link takes you to an external page) only: Key-value pairs of Template variables(link takes you to an external page) and their substitution values. content_sid parameter must also be provided. If values are not defined in the content_variables parameter, the Template's default placeholder values(link takes you to an external page) are used.


RiskChecktype: enum<STRING>Not PII

For SMS pumping protection feature only: Include this parameter with a value of disable to skip any kind of risk check on the respective message request.

Possible values:
enabledisable

Fromtype: string<PHONE NUMBER>PII MTL: 120 days
Required if MessagingServiceSid is not passed

The sender's Twilio phone number (in E.164(link takes you to an external page) format), alphanumeric sender ID(link takes you to an external page), Wireless SIM(link takes you to an external page), short code(link takes you to an external page), or channel address(link takes you to an external page) (e.g., whatsapp:+15554449999). The value of the from parameter must be a sender that is hosted within Twilio and belongs to the Account creating the Message. If you are using messaging_service_sid, this parameter can be empty (Twilio assigns a from value from the Messaging Service's Sender Pool) or you can provide a specific sender from your Sender Pool.


MessagingServiceSidtype: SID<MG>Not PII
Required if From is not passed

The SID of the Messaging Service(link takes you to an external page) you want to associate with the Message. When this parameter is provided and the from parameter is omitted, Twilio selects the optimal sender from the Messaging Service's Sender Pool. You may also provide a from parameter if you want to use a specific Sender from the Sender Pool.


Bodytype: stringPII MTL: 30 days
Required if MediaUrl or ContentSid is not passed

The text content of the outgoing message. Can be up to 1,600 characters in length. SMS only: If the body contains more than 160 GSM-7(link takes you to an external page) characters (or 70 UCS-2(link takes you to an external page) characters), the message is segmented and charged accordingly. For long body text, consider using the send_as_mms parameter(link takes you to an external page).


MediaUrltype: string[]Not PII
Required if Body or ContentSid is not passed

The URL of media to include in the Message content. jpeg, jpg, gif, and png file types are fully supported by Twilio and content is formatted for delivery on destination devices. The media size limit is 5 MB for supported file types (jpeg, jpg, png, gif) and 500 KB for other types(link takes you to an external page) of accepted media. To send more than one image in the message, provide multiple media_url parameters in the POST request. You can include up to ten media_url parameters per message. International(link takes you to an external page) and carrier(link takes you to an external page) limits apply.


ContentSidtype: SID<HX>Not PII
Required if Body or MediaUrl is not passed

For Content Editor/API(link takes you to an external page) only: The SID of the Content Template to be used with the Message, e.g., HXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. If this parameter is not provided, a Content Template is not used. Find the SID in the Console on the Content Editor page. For Content API users, the SID is found in Twilio's response when creating the Template(link takes you to an external page) or by fetching your Templates(link takes you to an external page).


Twilio's request to the StatusCallback URL

twilios-request-to-the-statuscallback-url page anchor

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.

PropertyDescription
MessageStatusThe status of the Message resource at the time the status callback request was sent.
ErrorCodeIf an error occurred (i.e. the MessageStatus is failed or undelivered), this property provides additional information about the failure.
(warning)

Warning

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.

Learn more about status callbacks:

SMS/MMS

smsmms page anchor

For most SMS/MMS Messages that have a Status of delivered or undelivered, Twilio's request to the StatusCallback URL contains an additional property:

PropertyDescription
RawDlrDoneDateThis property is a passthrough of the Done Date included in the DLR (Delivery Receipt) that Twilio received from the carrier.

The value is in YYMMDDhhmm format.
  • YY is last two digits of the year (00-99)
  • MM is the two-digit month (01-12)
  • DD is the two-digit day (01-31)
  • hh is the two-digit hour (00-23)
  • mm is the two-digit minute (00-59).
Learn more on the "Addition of RawDlrDoneDate to Delivered and Undelivered Status Webhooks" Changelog page(link takes you to an external page).

WhatsApp and other messaging channels

whatsapp-and-other-messaging-channels page anchor

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.

PropertyDescription
ChannelInstallSidThe Installed Channel SID that was used to send this message
ChannelStatusMessageThe error message returned by the underlying messaging channel if Message delivery failed. This property is present only if the Message delivery failed.
ChannelPrefixThe channel-specific prefix identifying the messaging channel associated with this Message
EventTypeThis property contains information about post-delivery events. If the channel supports read receipts (currently WhatsApp only), this property's value is READ after the recipient has read the 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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages
_10
.create({from: '+15557122661', body: 'Hi there', to: '+15558675310'})
_10
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Hi there",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15557122661",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}


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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.create({
_14
body: 'This is a WhatsApp message sent with Twilio!',
_14
from: 'whatsapp:+15555238886',
_14
to: 'whatsapp:+15557770006'
_14
})
_14
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is a WhatsApp message sent with Twilio!",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "whatsapp:+15555238886",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "whatsapp:+15557770006",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}


Send a message with a Messaging Service

send-a-message-with-a-messaging-service page anchor

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.

Send a message with a Messaging Service

send-a-message-with-a-messaging-service-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.create({
_14
messagingServiceSid: 'MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_14
body: 'Hello! This is a message sent from a Messaging Service.',
_14
to: '+15551212121'
_14
})
_14
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Hello! This is a message sent from a Messaging Service.",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+14155552345",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15551212121",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}


Fetch a Message resource

fetch-a-message-resource page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json

Returns a single Message resource specified by the provided Message SID.

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) associated with the Message resource


Sidtype: SID<SM|MM>Not PII
Path Parameter

The SID of the Message resource to be fetched

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "testing",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": 30007,
_25
"error_message": "Carrier violation",
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": "-0.00750",
_25
"price_unit": "USD",
_25
"sid": "MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}


Read multiple Message resources

read-multiple-message-resources page anchor
GET 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.

(warning)

Warning

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:

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) associated with the Message resources.


Totype: string<PHONE NUMBER>PII MTL: 120 days
Query Parameter

Filter by recipient. For example: Set this to parameter to +15558881111 to retrieve a list of Message resources with to properties of +15558881111


Fromtype: string<PHONE NUMBER>PII MTL: 120 days
Query Parameter

Filter by sender. For example: Set this from parameter to +15552229999 to retrieve a list of Message resources with from properties of +15552229999


DateSenttype: string<DATE TIME>Not PII
Query Parameter

Filter by Message sent_date. Accepts GMT dates in the following formats: YYYY-MM-DD (to find Messages with a specific sent_date), <=YYYY-MM-DD (to find Messages with sent_dates on and before a specific date), and >=YYYY-MM-DD (to find Messages with sent_dates on and after a specific date).


DateSent<type: string<DATE TIME>Not PII
Query Parameter

Filter by Message sent_date. Accepts GMT dates in the following formats: YYYY-MM-DD (to find Messages with a specific sent_date), <=YYYY-MM-DD (to find Messages with sent_dates on and before a specific date), and >=YYYY-MM-DD (to find Messages with sent_dates on and after a specific date).


DateSent>type: string<DATE TIME>Not PII
Query Parameter

Filter by Message sent_date. Accepts GMT dates in the following formats: YYYY-MM-DD (to find Messages with a specific sent_date), <=YYYY-MM-DD (to find Messages with sent_dates on and before a specific date), and >=YYYY-MM-DD (to find Messages with sent_dates on and after a specific date).


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

List all Message resources

list-all-message-resources page anchor

Returns a list of all Message resources associated with your Account

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages.list({limit: 20})
_10
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}

List Message resources matching filter criteria

list-message-resources-matching-filter-criteria page anchor

List all messages sent on August 31, 2016 from +15017122661 and to +15558675310

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messages
_15
.list({
_15
dateSent: new Date(Date.UTC(2016, 7, 31, 0, 0, 0)),
_15
from: '+15017122661',
_15
to: '+15558675310',
_15
limit: 20
_15
})
_15
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}

List Messages that were sent before a specific date

list-messages-that-were-sent-before-a-specific-date page anchor

List all Messages sent before March 1st, 2019

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.messages
_13
.list({
_13
dateSentBefore: new Date(Date.UTC(2019, 2, 1, 0, 0, 0)),
_13
limit: 20
_13
})
_13
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}

List Messages within a specific time period

list-messages-within-a-specific-time-period page anchor

List all Messages sent between January 15th, 2021, 01:23:45 UTC and January 17th, 2021, 01:23:45 UTC

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.list({
_14
dateSentAfter: new Date(Date.UTC(2021, 0, 15, 1, 23, 45)),
_14
dateSentBefore: new Date(Date.UTC(2021, 0, 17, 1, 23, 45)),
_14
limit: 20
_14
})
_14
.then(messages => messages.forEach(m => console.log(m.sid)));

Output

_70
{
_70
"end": 1,
_70
"first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=1&PageToken=PAMMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"page": 0,
_70
"page_size": 2,
_70
"previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0",
_70
"messages": [
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "testing",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:50 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:50 +0000",
_70
"direction": "outbound-api",
_70
"error_code": null,
_70
"error_message": null,
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "0",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "SMded05904ccb347238880ca9264e8fe1c",
_70
"status": "sent",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMded05904ccb347238880ca9264e8fe1c.json"
_70
},
_70
{
_70
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_70
"api_version": "2010-04-01",
_70
"body": "look mom I have media!",
_70
"date_created": "Fri, 24 May 2019 17:44:46 +0000",
_70
"date_sent": "Fri, 24 May 2019 17:44:49 +0000",
_70
"date_updated": "Fri, 24 May 2019 17:44:49 +0000",
_70
"direction": "inbound",
_70
"error_code": 30004,
_70
"error_message": "Message blocked",
_70
"from": "+12019235161",
_70
"messaging_service_sid": null,
_70
"num_media": "3",
_70
"num_segments": "1",
_70
"price": "-0.00750",
_70
"price_unit": "USD",
_70
"sid": "MMc26223853f8c46b4ab7dfaa6abba0a26",
_70
"status": "received",
_70
"subresource_uris": {
_70
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Media.json",
_70
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26/Feedback.json"
_70
},
_70
"tags": {
_70
"campaign_name": "Spring Sale 2022",
_70
"message_type": "cart_abandoned"
_70
},
_70
"to": "+18182008801",
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc26223853f8c46b4ab7dfaa6abba0a26.json"
_70
}
_70
],
_70
"start": 0,
_70
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json?To=%2B123456789&From=%2B987654321&DateSent%3E=2008-01-02&PageSize=2&Page=0"
_70
}


Update a Message resource

update-a-message-resource page anchor
POST 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.

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that created the Message resources to update.


Sidtype: SID<SM|MM>Not PII
Path Parameter

The SID of the Message resource to be updated


Request body parameters
Bodytype: stringPII MTL: 30 days

The new body of the Message resource. To redact the text content of a Message, this parameter's value must be an empty string


Statustype: enum<STRING>Not PII

Set as canceled to prevent a not-yet-sent Message from being sent. Can be used to cancel sending a scheduled Message(link takes you to an external page) (Messaging Services only).

Possible values:
canceled

Redact the body of a Message resource

redact-the-body-of-a-message-resource page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({body: ''})
_10
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": null,
_25
"error_message": null,
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": null,
_25
"price_unit": "USD",
_25
"sid": "SMb7c0a2ce80504485a6f653a7110836f5",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}


Delete a Message resource

delete-a-message-resource page anchor
DELETE 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.

(warning)

Warning

Message bodies may persist for up to 30 days after an HTTP DELETE request in our database backups.

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) associated with the Message resource


Sidtype: SID<SM|MM>Not PII
Path Parameter

The SID of the Message resource you wish to delete

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();


Rate this page: