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.

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
}