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.

Property nameTypePIIDescription
sidSID<IM>
Not PII

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

Pattern: ^IM[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

The SID of the Account that created the Message resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

attributesstring
PII MTL: 30 days

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


service_sidSID<IS>

The SID of the Service the Message resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

toSID<CH>

The SID of the Channel that the message was sent to.

Pattern: ^CH[0-9a-fA-F]{32}$Min length: 34Max length: 34

channel_sidSID<CH>

The SID of the Channel the Message resource belongs to.

Pattern: ^CH[0-9a-fA-F]{32}$Min length: 34Max length: 34

date_createdstring<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_updatedstring<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_bystring

The Identity of the User who last updated the Message, if applicable.


was_editedboolean

Whether the message has been edited since it was created.


The Identity of the message's author. The default value is system.


The content of the message.


indexinteger

The index of the message within the Channel. Indices may skip numbers, but will always be in order of when the message was received.


typestring

The Message type. Can be: text or media.


mediaobject

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.


urlstring<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.

Headers

headers page anchor
Property nameTypeRequiredPIIDescription
X-Twilio-Webhook-Enabledenum<string>Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse
Property nameTypeRequiredPIIDescription
ServiceSidSID<IS>required

The SID of the Service to create the Message resource under.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ChannelSidstringrequired

The SID of the Channel the new Message resource belongs to. This value can be the Channel resource's sid or unique_name.

Property nameTypeRequiredPIIDescription
FromstringOptional

The Identity of the new message's author. The default value is system.


AttributesstringOptional

A valid JSON string that contains application-specific data.


DateCreatedstring<date-time>Optional

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.


DateUpdatedstring<date-time>Optional

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.


LastUpdatedBystringOptional

The Identity of the User who last updated the Message, if applicable.


BodystringOptional

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.


MediaSidSID<ME>Optional

The SID of the Media to attach to the new Message.

Pattern: ^ME[0-9a-fA-F]{32}$Min length: 34Max length: 34

Create a Message resource

create-a-message-resource-1 page anchor
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
import twilio from "twilio";
_15
_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 = twilio(accountSid, authToken);
_15
_15
const message = await client.chat.v2
_15
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_15
.channels("ChannelSid")
_15
.messages.create({ body: "Hello, world!" });
_15
_15
console.log(message.sid);

Output

_18
{
_18
"sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"channel_sid": "ChannelSid",
_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/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_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.

Property nameTypeRequiredPIIDescription
ServiceSidSID<IS>required

The SID of the Service to fetch the Message resource from.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ChannelSidstringrequired

The SID of the Channel the Message resource to fetch belongs to. This value can be the Channel resource's sid or unique_name.


SidSID<IM>required

The SID of the Message resource to fetch.

Pattern: ^IM[0-9a-fA-F]{32}$Min length: 34Max length: 34
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const message = await client.chat.v2
_16
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_16
.channels("ChannelSid")
_16
.messages("IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_16
.fetch();
_16
_16
console.log(message.to);

Output

_18
{
_18
"sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"channel_sid": "ChannelSid",
_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/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_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.

Property nameTypeRequiredPIIDescription
ServiceSidSID<IS>required

The SID of the Service to read the Message resources from.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ChannelSidstringrequired

The SID of the Channel the Message resource to read belongs to. This value can be the Channel resource's sid or unique_name.

Property nameTypeRequiredPIIDescription
Orderenum<string>Optional

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

Possible values:
ascdesc

PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

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

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
import twilio from "twilio";
_15
_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 = twilio(accountSid, authToken);
_15
_15
const messages = await client.chat.v2
_15
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_15
.channels("ChannelSid")
_15
.messages.list({ limit: 20 });
_15
_15
messages.forEach((m) => console.log(m.sid));

Output

_31
{
_31
"messages": [
_31
{
_31
"sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_31
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_31
"attributes": "attributes",
_31
"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_31
"to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_31
"channel_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_31
"date_created": "2009-07-06T20:30:00Z",
_31
"date_updated": "2009-07-06T20:30:00Z",
_31
"last_updated_by": "last_updated_by",
_31
"was_edited": true,
_31
"from": "from",
_31
"body": "body",
_31
"index": 129,
_31
"type": "type",
_31
"media": "cannot-guess",
_31
"url": "https://www.example.com"
_31
}
_31
],
_31
"meta": {
_31
"first_page_url": "https://www.example.com",
_31
"key": "key",
_31
"next_page_url": "https://www.example.com",
_31
"page": 571,
_31
"page_size": 252,
_31
"previous_page_url": "https://www.example.com",
_31
"url": "https://www.example.com"
_31
}
_31
}


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.

Property nameTypeRequiredPIIDescription
X-Twilio-Webhook-Enabledenum<string>Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse
Property nameTypeRequiredPIIDescription
ServiceSidSID<IS>required

The SID of the Service to update the Message resource in.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ChannelSidstringrequired

The SID of the Channel the Message resource to update belongs to. This value can be the Channel resource's sid or unique_name.


SidSID<IM>required

The SID of the Message resource to update.

Pattern: ^IM[0-9a-fA-F]{32}$Min length: 34Max length: 34
Property nameTypeRequiredPIIDescription
BodystringOptional

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.


AttributesstringOptional

A valid JSON string that contains application-specific data.


DateCreatedstring<date-time>Optional

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.


DateUpdatedstring<date-time>Optional

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.


LastUpdatedBystringOptional

The Identity of the User who last updated the Message, if applicable.


FromstringOptional

The Identity of the message's author.

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

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const message = await client.chat.v2
_16
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_16
.channels("ChannelSid")
_16
.messages("IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_16
.update({ body: "This will be the body of the new message!" });
_16
_16
console.log(message.to);

Output

_18
{
_18
"sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18
"channel_sid": "ChannelSid",
_18
"attributes": "{ \"foo\": \"bar\" }",
_18
"date_created": "2015-12-16T22:18:37Z",
_18
"date_updated": "2015-12-16T22:18:38Z",
_18
"last_updated_by": "username",
_18
"was_edited": true,
_18
"from": "fromUser",
_18
"body": "This will be the body of the new message!",
_18
"index": 0,
_18
"type": "text",
_18
"media": null,
_18
"url": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_18
}


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.

Property nameTypeRequiredPIIDescription
X-Twilio-Webhook-Enabledenum<string>Optional

The X-Twilio-Webhook-Enabled HTTP request header

Possible values:
truefalse
Property nameTypeRequiredPIIDescription
ServiceSidSID<IS>required

The SID of the Service to delete the Message resource from.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

ChannelSidstringrequired

The SID of the Channel the Message resource to delete belongs to. This value can be the Channel resource's sid or unique_name.


SidSID<IM>required

The SID of the Message resource to delete.

Pattern: ^IM[0-9a-fA-F]{32}$Min length: 34Max length: 34
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
import twilio from "twilio";
_14
_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 = twilio(accountSid, authToken);
_14
_14
await client.chat.v2
_14
.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_14
.channels("ChannelSid")
_14
.messages("IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_14
.remove();


Rate this page: