Skip to contentSkip to navigationSkip to topbar
Twilio Docs
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: 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>
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: string
PII MTL: 30 days

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

was_editedtype: boolean
Not PII

Whether the message has been edited since it was created.

fromtype: string
PII MTL: 30 days

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

bodytype: string
PII MTL: 30 days

The content of the message.

indextype: integer
Not 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: string
Not PII

The Message type. Can be: text or media.

mediatype: object
PII 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>
Path ParameterNot PII

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

ChannelSidtype: string
Path ParameterNot PII

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: string
PII MTL: 30 days

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

Attributestype: string
PII 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: string
PII MTL: 30 days

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

Bodytype: string
PII 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.

Create a Message resource

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

Parameters

fetch-parameters page anchor
URI parameters
ServiceSidtype: SID<IS>
Path ParameterNot PII

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

ChannelSidtype: string
Path ParameterNot PII

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 ParameterNot PII

The SID of the Message resource to fetch.

Fetch a Message resource

fetch-a-message-resource-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('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.

Parameters

list-parameters page anchor
URI parameters
ServiceSidtype: SID<IS>
Path ParameterNot PII

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

ChannelSidtype: string
Path ParameterNot PII

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 ParameterNot PII

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 ParameterNot PII

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

Pagetype: integer
Query ParameterNot PII

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

PageTokentype: string
Query ParameterNot PII

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.

Parameters

update-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>
Path ParameterNot PII

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

ChannelSidtype: string
Path ParameterNot PII

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 ParameterNot PII

The SID of the Message resource to update.

Request body parameters
Bodytype: string
PII 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: string
PII 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: string
PII MTL: 30 days

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

Fromtype: string
PII MTL: 30 days

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

Update a Message resource

update-a-message-resource-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('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.

Parameters

delete-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>
Path ParameterNot PII

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

ChannelSidtype: string
Path ParameterNot PII

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 ParameterNot PII

The SID of the Message resource to delete.

Delete a Message resource

delete-a-message-resource-1 page anchor
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: