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

Programmable Chat Message Resource


(error)

Danger

Programmable Chat has been deprecated and is no longer supported. Instead, we'll be focusing on the next generation of chat: Twilio Conversations. Find out more about the EOL process here(link takes you to an external page).

If you're starting a new project, please visit the Conversations Docs to begin. If you've already built on Programmable Chat, please visit our Migration Guide to learn about how to switch.

The Message resource of Programmable Chat represents a single message within a Channel in a Service instance. Creating a new Message resource sends a message to the Channel. Fetching and Reading Message resources provide information about previously sent messages.


Message Properties

message-properties page anchor

Each Message resource contains these properties.

Resource properties
sidtype: SID<IM>Not PII

The unique string that we created to identify the Message resource.


account_sidtype: SID<AC>Not PII

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


attributestype: stringPII MTL: 30 days

The JSON string that stores application-specific data. If attributes have not been set, {} is returned.


service_sidtype: SID<IS>Not PII

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


totype: SID<CH>Not PII

The SID of the Channel(link takes you to an external page) that the message was sent to.


channel_sidtype: SID<CH>Not PII

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


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


last_updated_bytype: stringPII MTL: 30 days

The Identity(link takes you to an external page) of the User who last updated the Message, if applicable.


was_editedtype: booleanNot PII

Whether the message has been edited since it was created.


fromtype: stringPII MTL: 30 days

The Identity(link takes you to an external page) of the message's author. The default value is system.


bodytype: stringPII MTL: 30 days

The content of the message.


indextype: integerNot PII

The index of the message within the Channel(link takes you to an external page). Indices may skip numbers, but will always be in order of when the message was received.


typetype: stringNot PII

The Message type. Can be: text or media.


mediatype: objectPII MTL: 30 days

An object that describes the Message's media, if the message contains media. The object contains these fields: content_type with the MIME type of the media, filename with the name of the media, sid with the SID of the Media resource, and size with the media object's file size in bytes. If the Message has no media, this value is null.


urltype: string<URI>Not PII

The absolute URL of the Message resource.


Create a Message resource

create-a-message-resource page anchor
POST https://chat.twilio.com/v2/Services/{ServiceSid}/Channels/{ChannelSid}/Messages

The {ChannelSid} value can be the Channel resource's sid or unique_name.

Creating a new Message resource in a Channel sends a message to the Channel.

Parameters

create-parameters page anchor
Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to create the Message resource under.


ChannelSidtype: stringNot PII
Path Parameter

The SID of the Channel(link takes you to an external page) the new Message resource belongs to. This value can be the Channel resource's sid or unique_name.


Request body parameters
Fromtype: stringPII MTL: 30 days

The Identity(link takes you to an external page) of the new message's author. The default value is system.


Attributestype: stringPII MTL: 30 days

A valid JSON string that contains application-specific data.


DateCreatedtype: string<DATE TIME>Not PII

The date, specified in ISO 8601(link takes you to an external page) format, to assign to the resource as the date it was created. The default value is the current time set by the Chat service. This parameter should only be used when a Chat's history is being recreated from a backup/separate source.


DateUpdatedtype: string<DATE TIME>Not PII

The date, specified in ISO 8601(link takes you to an external page) format, to assign to the resource as the date it was last updated.


LastUpdatedBytype: stringPII MTL: 30 days

The Identity(link takes you to an external page) of the User who last updated the Message, if applicable.


Bodytype: stringPII MTL: 30 days

The message to send to the channel. Can be an empty string or null, which sets the value as an empty string. You can send structured data in the body by serializing it as a string.


MediaSidtype: SID<ME>Not PII

The SID of the Media(link takes you to an external page) to attach to the new Message.

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

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = require('twilio')(accountSid, authToken);
_12
_12
client.chat.v2.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12
.channels('CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12
.messages
_12
.create({body: 'Hello, world!'})
_12
.then(message => console.log(message.sid));

Output

_18
{
_18
"sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"to": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"attributes": null,
_18
"date_created": "2016-03-24T20:37:57Z",
_18
"date_updated": "2016-03-24T20:37:57Z",
_18
"last_updated_by": "system",
_18
"was_edited": false,
_18
"from": "system",
_18
"body": "Hello, world!",
_18
"index": 0,
_18
"type": "text",
_18
"media": null,
_18
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_18
}


Fetch a Message resource

fetch-a-message-resource page anchor
GET https://chat.twilio.com/v2/Services/{ServiceSid}/Channels/{ChannelSid}/Messages/{Sid}

The {ChannelSid} value can be the Channel resource's sid or unique_name.

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to fetch the Message resource from.


ChannelSidtype: stringNot PII
Path Parameter

The SID of the Channel(link takes you to an external page) the Message resource to fetch belongs to. This value can be the Channel resource's sid or unique_name.


Sidtype: SID<IM>Not PII
Path Parameter

The SID of the Message resource to fetch.

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

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

Output

_18
{
_18
"sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"to": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18
"date_created": "2016-03-24T20:37:57Z",
_18
"date_updated": "2016-03-24T20:37:57Z",
_18
"last_updated_by": null,
_18
"was_edited": false,
_18
"from": "system",
_18
"attributes": {},
_18
"body": "Hello",
_18
"index": 0,
_18
"type": "text",
_18
"media": null,
_18
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_18
}


Read multiple Message resources

read-multiple-message-resources page anchor
GET https://chat.twilio.com/v2/Services/{ServiceSid}/Channels/{ChannelSid}/Messages

The {ChannelSid} value can be the Channel resource's sid or unique_name.

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to read the Message resources from.


ChannelSidtype: stringNot PII
Path Parameter

The SID of the Channel(link takes you to an external page) the Message resource to read belongs to. This value can be the Channel resource's sid or unique_name.


Ordertype: enum<STRING>Not PII
Query Parameter

The sort order of the returned messages. Can be: asc (ascending) or desc (descending) with asc as the default.

Possible values:
ascdesc

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.

Read multiple Message resources

read-multiple-message-resources-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_54
{
_54
"meta": {
_54
"page": 0,
_54
"page_size": 50,
_54
"first_page_url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages?PageSize=50&Page=0",
_54
"previous_page_url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages?PageSize=50&Page=0",
_54
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages?PageSize=50&Page=0",
_54
"next_page_url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages?PageSize=50&Page=1",
_54
"key": "messages"
_54
},
_54
"messages": [
_54
{
_54
"sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"to": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"date_created": "2016-03-24T20:37:57Z",
_54
"date_updated": "2016-03-24T20:37:57Z",
_54
"last_updated_by": null,
_54
"was_edited": false,
_54
"from": "system",
_54
"attributes": {},
_54
"body": "Hello",
_54
"index": 0,
_54
"type": "text",
_54
"media": null,
_54
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_54
},
_54
{
_54
"sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"to": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"date_created": "2016-03-24T20:37:57Z",
_54
"date_updated": "2016-03-24T20:37:57Z",
_54
"last_updated_by": null,
_54
"was_edited": false,
_54
"from": "system",
_54
"attributes": {},
_54
"body": "Hello",
_54
"index": 0,
_54
"type": "media",
_54
"media": {
_54
"sid": "MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_54
"size": 99999999999999,
_54
"content_type": "application/pdf",
_54
"filename": "hello.pdf"
_54
},
_54
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_54
}
_54
]
_54
}


Update a Message resource

update-a-message-resource page anchor
POST https://chat.twilio.com/v2/Services/{ServiceSid}/Channels/{ChannelSid}/Messages/{Sid}

The {ChannelSid} value can be the Channel resource's sid or unique_name.

Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to update the Message resource in.


ChannelSidtype: stringNot PII
Path Parameter

The SID of the Channel(link takes you to an external page) the Message resource to update belongs to. This value can be the Channel resource's sid or unique_name.


Sidtype: SID<IM>Not PII
Path Parameter

The SID of the Message resource to update.


Request body parameters
Bodytype: stringPII MTL: 30 days

The message to send to the channel. Can be an empty string or null, which sets the value as an empty string. You can send structured data in the body by serializing it as a string.


Attributestype: stringPII MTL: 30 days

A valid JSON string that contains application-specific data.


DateCreatedtype: string<DATE TIME>Not PII

The date, specified in ISO 8601(link takes you to an external page) format, to assign to the resource as the date it was created. The default value is the current time set by the Chat service. This parameter should only be used when a Chat's history is being recreated from a backup/separate source.


DateUpdatedtype: string<DATE TIME>Not PII

The date, specified in ISO 8601(link takes you to an external page) format, to assign to the resource as the date it was last updated.


LastUpdatedBytype: stringPII MTL: 30 days

The Identity(link takes you to an external page) of the User who last updated the Message, if applicable.


Fromtype: stringPII MTL: 30 days
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_20
{
_20
"sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"to": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"attributes": {
_20
"foo": "bar"
_20
},
_20
"date_created": "2015-12-16T22:18:37Z",
_20
"date_updated": "2015-12-16T22:18:38Z",
_20
"last_updated_by": "username",
_20
"was_edited": true,
_20
"from": "fromUser",
_20
"body": "Hello",
_20
"index": 0,
_20
"type": "text",
_20
"media": null,
_20
"url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_20
}


Delete a Message resource

delete-a-message-resource page anchor
DELETE https://chat.twilio.com/v2/Services/{ServiceSid}/Channels/{ChannelSid}/Messages/{Sid}

The {ChannelSid} value can be the Channel resource's sid or unique_name.

Request headers
X-Twilio-Webhook-Enabledtype: enum<STRING>Not PII

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to delete the Message resource from.


ChannelSidtype: stringNot PII
Path Parameter

The SID of the Channel(link takes you to an external page) the Message resource to delete belongs to. This value can be the Channel resource's sid or unique_name.


Sidtype: SID<IM>Not PII
Path Parameter

The SID of the Message resource to delete.

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

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


Rate this page: