Skip to content Skip to navigation Skip to topbar

On this page

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

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.

(error)

Danger

This is reference documentation for the v1 REST API, which has been deprecated. You should use the current v2 REST API.

The Message resource of Programmable Chat represents a single message within a Channel in a Service instance. POSTing to the Messages resource of a Channel allows you to send messages to the Channel via the REST API.

Properties

Each message has these properties:

Property nameTypeRequiredDescriptionChild properties

sidSID<IM>

Optional

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>

Optional

Not PII

The SID of the Account that created the Message resource.

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

attributesstring

Optional

PII MTL: 30 days

The JSON string that stores application-specific data. Note If this property has been assigned a value, it's only displayed in a FETCH action that returns a single resource; otherwise, it's null. If the attributes have not been set, {} is returned.

service_sidSID<IS>

Optional

Not PII

The SID of the Service the resource is associated with.

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

toSID<CH>

Optional

Not PII

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>

Optional

Not PII

The unique ID of the Channel the Message resource belongs to.

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

date_createdstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

date_updatedstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

was_editedboolean

Optional

Not PII

Whether the message has been edited since it was created.

fromstring

Optional

PII MTL: 30 days

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

bodystring

Optional

PII MTL: 30 days

The content of the message.

indexinteger

Optional

Not PII

The index of the message within the Channel.

Default: 0

urlstring<uri>

Optional

Not PII

The absolute URL of the Message resource.

List All Messages in a Channel

1GET /Services/{Instance SID}/Channels/{Channel SID}/Messages
2

List all Messages

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listMessage() {
11  const messages = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .messages.list({ limit: 20 });
15
16  messages.forEach((m) => console.log(m.sid));
17}
18
19listMessage();

Output

1{
2  "meta": {
3    "page": 0,
4    "page_size": 50,
5    "first_page_url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages?PageSize=50&Page=0",
6    "previous_page_url": null,
7    "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages?PageSize=50&Page=0",
8    "next_page_url": null,
9    "key": "messages"
10  },
11  "messages": [
12    {
13      "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17      "channel_sid": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18      "date_created": "2016-03-24T20:37:57Z",
19      "date_updated": "2016-03-24T20:37:57Z",
20      "was_edited": false,
21      "from": "system",
22      "attributes": "{}",
23      "body": "Hello",
24      "index": 0,
25      "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
26    }
27  ]
28}

Send a Message to a Channel

1POST /Services/{Instance SID}/Channels/{Channel SID}/Messages
2

Parameters

name	description
Body	A string message to send to this channel. You can also send structured data by serializing it into a string.
Attributes	An optional metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified.
From	The optional [identity][identity] of the message's author. Defaults to `system` if not specified.

Send a Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .messages.create({ body: "MESSAGE" });
15
16  console.log(message.sid);
17}
18
19createMessage();

Output

1{
2  "sid": "IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7  "attributes": null,
8  "date_created": "2016-03-24T20:37:57Z",
9  "date_updated": "2016-03-24T20:37:57Z",
10  "was_edited": false,
11  "from": "system",
12  "body": "MESSAGE",
13  "index": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15}

Retrieve a Message from a Channel

1GET /Services/{Instance SID}/Channels/{Channel SID}/Messages/{Message SID}
2

Retrieve a Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchMessage() {
11  const message = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .messages("IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
15    .fetch();
16
17  console.log(message.sid);
18}
19
20fetchMessage();

Output

1{
2  "sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7  "date_created": "2016-03-24T20:37:57Z",
8  "date_updated": "2016-03-24T20:37:57Z",
9  "was_edited": false,
10  "from": "system",
11  "attributes": "{}",
12  "body": "Hello",
13  "index": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15}

Update an existing Message

1POST /Services/{Instance SID}/Channels/{Channel SID}/Messages/{Message SID}
2

Parameters

Path parameters

Property nameTypeRequiredPIIDescription

ServiceSidSID<IS>required

Not PII

The SID of the Service to update the resource from.

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

ChannelSidSID<CH>required

Not PII

The unique ID of the Channel the message belongs to. Can be the Channel's sid or unique_name.

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

SidSID<IM>required

Not PII

The Twilio-provided string that uniquely identifies the Message resource to update.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

Bodystring

Optional

PII MTL: 30 days

The message to send to the channel. Can also 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.

Attributesstring

Optional

PII MTL: 30 days

A valid JSON string that contains application-specific data.

Update a Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateMessage() {
11  const message = await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .messages("IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
15    .update({ body: "MESSAGE" });
16
17  console.log(message.sid);
18}
19
20updateMessage();

Output

1{
2  "sid": "IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5  "to": "CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "channel_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7  "attributes": "{\"test\": \"test\"}",
8  "date_created": "2016-03-24T20:37:57Z",
9  "date_updated": "2016-03-24T20:37:57Z",
10  "was_edited": false,
11  "from": "system",
12  "body": "MESSAGE",
13  "index": 0,
14  "url": "https://chat.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels/CHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/IMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
15}

Delete a Message from a Channel

1DELETE /Services/{Instance SID}/Channels/{Channel SID}/Messages/{Message SID}
2

Delete a Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteMessage() {
11  await client.chat.v1
12    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13    .channels("CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14    .messages("IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
15    .remove();
16}
17
18deleteMessage();