Skip to contentSkip to navigationSkip to topbar
Twilio Docs

Conversations API (v2) - Communication endpoints

(information)

Legal information

Conversation Orchestrator, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum(link takes you to an external page). For details on AI usage and data, see the AI Nutrition Facts for Real-Time Transcription and Conversation Relay.

Conversation Orchestrator is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console(link takes you to an external page). If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

overview page anchor

A communication is the smallest unit of interaction within a conversation. Each communication represents a single event—such as an SMS message or a voice utterance.

Endpoints

Create Communication

create-communication-in-conversation page anchor

POST/v2/Conversations/{ConversationSid}/Communications

Base url: https://conversations.twilio.com (base url)

Create a Communication.

Request

create-communication-in-conversation-request page anchor

Path parameters

create-communication-in-conversation-path-parameters page anchor
Property nameTypeRequiredPIIDescription
conversationSidstring
required
Not PII

Request body

create-communication-in-conversation-request-body page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
authorobject
required
Not PII
content
oneOf:
required
Not PII

The content of the Communication.

channelIdstring

Optional

Not PII
recipientsarray[object]
required
Not PII
Min items: 1

Responses

create-communication-in-conversation-responses page anchor
201400404429500503

Created

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
idstring

Optional

Not PII

Communication ID.

Example: conv_communication_01k1etk2y5f1y9fpe2epfdtvv2
conversationIdstring

Optional

Not PII

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2
accountIdstring

Optional

Not PII

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
authorobject

Optional

Not PII
Example: {"address":"+18005550100","channel":"SMS","participantId":"conv_participant_01k1etx3jbfx88476ccja0889c"}
content
oneOf:

Optional

Not PII

The content of the Communication using type field for discrimination.

channelIdstring

Optional

Not PII

Channel-specific reference ID.

Example: CA123456789
resourceIdstring

Optional

Not PII

External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.

Example: SM12345678901234567890123456789012Min length: 1
recipientsarray[object]

Optional

Not PII

Communication recipients.

createdAtstring<date-time>

Optional

Not PII

Timestamp when this Communication was created.

Example: 2023-07-01T12:15:00Z
updatedAtstring<date-time>

Optional

Not PII

Timestamp when this Communication was last updated.

Example: 2023-07-01T12:15:00Z
occurredAtstring<date-time>

Optional

Not PII

ISO 8601 timestamp when the communication occurred.

Example: 2023-07-01T12:15:00Z
Create CommunicationLink to code sample: Create Communication
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createCommunicationInConversation() {

11
  const communication = await client.conversations.v2

12
    .communications("ConversationSid")

13
    .create({

14
      author: {

15
        address: "address",

16
        channel: "VOICE",

17
        participantId: "participantId",

18
      },

19
      content: {

20
        type: "TEXT",

21
        text: "text",

22
      },

23
      recipients: [

24
        {

25
          address: "address",

26
          channel: "VOICE",

27
          participantId: "participantId",

28
        },

29
      ],

30
    });

31


32
  console.log(communication.id);

33
}

34


35
createCommunicationInConversation();

Response

Note about this response
1
{

2
  "accountId": "ZGkrHSypTsudrGkmdpJJ",

3
  "author": {

4
    "address": "address",

5
    "channel": "VOICE",

6
    "participantId": "participantId"

7
  },

8
  "channelId": "channelId",

9
  "content": {

10
    "type": "TEXT",

11
    "text": "text"

12
  },

13
  "conversationId": "conversationId",

14
  "createdAt": "2009-07-06T20:30:00Z",

15
  "id": "id",

16
  "occurredAt": "2009-07-06T20:30:00Z",

17
  "recipients": [

18
    {

19
      "address": "address",

20
      "channel": "VOICE",

21
      "participantId": "participantId"

22
    }

23
  ],

24
  "resourceId": "resourceId",

25
  "updatedAt": "2009-07-06T20:30:00Z"

26
}

List Communications

list-communication-by-conversation page anchor

GET/v2/Conversations/{ConversationSid}/Communications

Base url: https://conversations.twilio.com (base url)

Retrieve a list of Communications in a Conversation.

Request

list-communication-by-conversation-request page anchor

Path parameters

list-communication-by-conversation-path-parameters page anchor
Property nameTypeRequiredPIIDescription
conversationSidstring
required
Not PII

Query string

list-communication-by-conversation-query-string page anchor
Property nameTypeRequiredPIIDescription
channelIdstring

Optional

Not PII

Resource identifier to filter communications

pageSizeinteger

Optional

Not PII

Maximum number of items to return

Default: 50Example: 50Minimum: 1Maximum: 1000
pageTokenstring

Optional

Not PII

Page token for pagination

Responses

list-communication-by-conversation-responses page anchor
200400404429500503

OK

Schema
Property nameTypeRequiredPIIDescriptionChild properties
communicationsarray[object]

Optional

Not PII
metaobject

Optional

Not PII
List CommunicationsLink to code sample: List Communications
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listCommunicationByConversation() {

11
  const communications = await client.conversations.v2

12
    .communications("ConversationSid")

13
    .list({ limit: 20 });

14


15
  communications.forEach((c) => console.log(c.id));

16
}

17


18
listCommunicationByConversation();

Response

Note about this response
1
{

2
  "communications": [

3
    {

4
      "id": "id",

5
      "conversationId": "conversationId",

6
      "accountId": "accountId",

7
      "author": {

8
        "address": "address",

9
        "channel": "SMS",

10
        "participantId": "participantId"

11
      },

12
      "content": "cannot-guess",

13
      "channelId": "channelId",

14
      "resourceId": "resourceId",

15
      "recipients": [

16
        {

17
          "address": "address",

18
          "channel": "SMS",

19
          "participantId": "participantId",

20
          "deliveryStatus": "INITIATED"

21
        }

22
      ],

23
      "createdAt": "2009-07-06T20:30:00Z",

24
      "updatedAt": "2009-07-06T20:30:00Z",

25
      "occurredAt": "2009-07-06T20:30:00Z"

26
    }

27
  ],

28
  "meta": {

29
    "key": "key",

30
    "pageSize": 42,

31
    "previousToken": "previousToken",

32
    "nextToken": "nextToken"

33
  }

34
}

Fetch Communication

fetch-communication page anchor

GET/v2/Conversations/{ConversationSid}/Communications/{Sid}

Base url: https://conversations.twilio.com (base url)

Retrieve a Communication.

Request

fetch-communication-request page anchor

Path parameters

fetch-communication-path-parameters page anchor
Property nameTypeRequiredPIIDescription
conversationSidstring
required
Not PII
sidstring
required
Not PII

Responses

fetch-communication-responses page anchor
200400404429500503

OK

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
idstring

Optional

Not PII

Communication ID.

Example: conv_communication_01k1etk2y5f1y9fpe2epfdtvv2
conversationIdstring

Optional

Not PII

Conversation ID.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2
accountIdstring

Optional

Not PII

Account ID.

Example: ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
authorobject

Optional

Not PII
Example: {"address":"+18005550100","channel":"SMS","participantId":"conv_participant_01k1etx3jbfx88476ccja0889c"}
content
oneOf:

Optional

Not PII

The content of the Communication using type field for discrimination.

channelIdstring

Optional

Not PII

Channel-specific reference ID.

Example: CA123456789
resourceIdstring

Optional

Not PII

External resource identifier for this Communication (e.g. MessageSid for SMS/RCS/WhatsApp, TranscriptionSid + MessageIndex for Voice). When set, used for Communication deduplication/uniqueness within a Conversation.

Example: SM12345678901234567890123456789012Min length: 1
recipientsarray[object]

Optional

Not PII

Communication recipients.

createdAtstring<date-time>

Optional

Not PII

Timestamp when this Communication was created.

Example: 2023-07-01T12:15:00Z
updatedAtstring<date-time>

Optional

Not PII

Timestamp when this Communication was last updated.

Example: 2023-07-01T12:15:00Z
occurredAtstring<date-time>

Optional

Not PII

ISO 8601 timestamp when the communication occurred.

Example: 2023-07-01T12:15:00Z
Fetch CommunicationLink to code sample: Fetch Communication
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const 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

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchCommunication() {

11
  const communication = await client.conversations.v2

12
    .communications("ConversationSid", "Sid")

13
    .fetch();

14


15
  console.log(communication.id);

16
}

17


18
fetchCommunication();

Response

Note about this response
1
{

2
  "accountId": "ZGkrHSypTsudrGkmdpJJ",

3
  "author": {

4
    "address": "address",

5
    "channel": "SMS",

6
    "participantId": "participantId"

7
  },

8
  "channelId": "channelId",

9
  "content": {},

10
  "conversationId": "conversationId",

11
  "createdAt": "2009-07-06T20:30:00Z",

12
  "id": "id",

13
  "occurredAt": "2009-07-06T20:30:00Z",

14
  "recipients": [

15
    {

16
      "address": "address",

17
      "channel": "SMS",

18
      "participantId": "participantId",

19
      "deliveryStatus": "INITIATED"

20
    }

21
  ],

22
  "resourceId": "resourceId",

23
  "updatedAt": "2009-07-06T20:30:00Z"

24
}