Skip to contentSkip to navigationSkip to topbar
Rate 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>

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


account_sidtype: SID<AC>

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


attributestype: string
PII MTL: 30 days

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


service_sidtype: SID<IS>

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


totype: SID<CH>

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


channel_sidtype: SID<CH>

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


date_createdtype: string<DATE TIME>

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>

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: string

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


was_editedtype: boolean

Whether the message has been edited since it was created.


fromtype: string

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


bodytype: string

The content of the message.


indextype: integer

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: string

The Message type. Can be: text or media.


mediatype: object

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>

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
URI parameters
ServiceSidtype: SID<IS>
Path Parameter

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


ChannelSidtype: string
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.


X-Twilio-Webhook-Enabledtype: enum<STRING>
Header Parameter

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

Request body parameters
Fromtype: string

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


Attributestype: string

A valid JSON string that contains application-specific data.


DateCreatedtype: string<DATE TIME>

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>

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: string

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


Bodytype: string

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>

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>
Path Parameter

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


ChannelSidtype: string
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>
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>
Path Parameter

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


ChannelSidtype: string
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>
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: integer
Query Parameter

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


Pagetype: integer
Query Parameter

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


PageTokentype: string
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.

URI parameters
ServiceSidtype: SID<IS>
Path Parameter

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


ChannelSidtype: string
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>
Path Parameter

The SID of the Message resource to update.


X-Twilio-Webhook-Enabledtype: enum<STRING>
Header Parameter

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse

Request body parameters
Bodytype: string

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: string

A valid JSON string that contains application-specific data.


DateCreatedtype: string<DATE TIME>

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>

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: string

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


Fromtype: string
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.

URI parameters
ServiceSidtype: SID<IS>
Path Parameter

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


ChannelSidtype: string
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>
Path Parameter

The SID of the Message resource to delete.


X-Twilio-Webhook-Enabledtype: enum<STRING>
Header Parameter

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse
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: