Conversations API (v2) - Action 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. 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. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

Perform actions within a Conversation. Actions trigger side effects such as sending messages and return 202 Accepted.

Endpoints

/v2/Conversations/{ConversationId}/Actions

Create an Action

/v2/Conversations/{ConversationId}/Actions/{ActionId}

Get Action Status

Create an Action

POST/v2/Conversations/{ConversationId}/Actions

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

Creates an Action within a Conversation. Currently supports SEND_MESSAGE, which sends a message to recipients via the configured channel.

Returns 202 Accepted with the Action in PENDING status. Poll GET /v2/Conversations/{ConversationId}/Actions/{ActionId} to check completion.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationIdstring

required

Request body

Encoding type:application/json

SchemaExample

Select from possible schemas

Property nameTypeRequiredPIIDescriptionChild properties

typestring

required

Action type discriminator. Accepted values: SEND_MESSAGE.

Example: SEND_MESSAGE

payloadobject

required

Show payload properties

Property nameTypeRequiredPIIDescriptionChild properties

fromobject

required

Identifies a participant for an Action. Supports three resolution modes:

participantId + channel: Resolves address from participant's registered addresses
participantId only: Resolves when participant has exactly one address
address + channel: Uses explicit address

Show from properties

toarray[object]

required

The recipients of this action.

Min items: 1

Show to properties

contentobject

required

Content for a SEND_MESSAGE action.

Show content properties

channelSettingsobject

Optional

Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

Example: {"messagingServiceSid":"MG1234567890abcdef1234567890abcdef","statusCallback":"https://example.com/status"}

Show channelSettings properties

Responses

202400404429500503

Action accepted. Returns the Action in PENDING status.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Unique identifier for this Action.

Example: conv_action_01k1etx3jbfx88476ccja0889e

typestring

Optional

The type of action. Accepted values: SEND_MESSAGE.

Example: SEND_MESSAGE

statusenum<string>

Optional

Current status of the Action.

PENDING: Action accepted, awaiting downstream confirmation
COMPLETED: Downstream backend confirmed the action
FAILED: Downstream backend reported a failure

Example: PENDINGPossible values:

PENDINGCOMPLETEDFAILED

conversationIdstring

Optional

The conversation this action belongs to.

Example: conv_conversation_01k1etx3jbfx88476ccja0889c

relatedobject

Optional

Named identifiers from downstream. For SEND_MESSAGE:

messageSid: The downstream message SID (present when PENDING or COMPLETED)
communicationId: The Communication ID (present when COMPLETED)

Example: {"messageSid":"SM1234567890abcdef1234567890abcdef","communicationId":"conv_communication_01k1etx3jbfx88476ccja0889c"}

Show related properties

createdAtstring<date-time>

Optional

Timestamp when the action was created.

Example: 2026-03-30T10:30:00Z

updatedAtstring<date-time>

Optional

Timestamp when the action was last updated.

Example: 2026-03-30T10:30:02Z

completedAtstring<date-time>

Optional

Timestamp when the action reached a terminal status.

Example: 2026-03-30T10:30:02Z

Create an Action

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 createConversationAction() {
11  const action = await client.conversations.v2
12    .actions("ConversationId")
13    .create({
14      type: "type",
15      payload: {
16        from: {
17          participantId: "participantId",
18          address: "address",
19          channel: "VOICE",
20        },
21        to: [
22          {
23            participantId: "participantId",
24            address: "address",
25            channel: "VOICE",
26          },
27        ],
28        content: {
29          text: "text",
30          contentId: "contentId",
31          variables: {},
32          mediaUrls: ["https://www.example.com"],
33        },
34        channelSettings: {},
35      },
36    });
37
38  console.log(action.id);
39}
40
41createConversationAction();

Response

1{
2  "completedAt": "2009-07-06T20:30:00Z",
3  "conversationId": "conversationId",
4  "createdAt": "2009-07-06T20:30:00Z",
5  "id": "id",
6  "related": {},
7  "status": "PENDING",
8  "type": "type",
9  "updatedAt": "2009-07-06T20:30:00Z"
10}

Get Action Status

GET/v2/Conversations/{ConversationId}/Actions/{ActionId}

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

Retrieve the current status of an Action.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

conversationIdstring

required

actionIdstring

required

Responses

200400404429500503

Action status.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

Optional

Unique identifier for this Action.

Example: conv_action_01k1etx3jbfx88476ccja0889e

typestring

Optional

The type of action. Accepted values: SEND_MESSAGE.

Example: SEND_MESSAGE

statusenum<string>

Optional

Current status of the Action.

PENDING: Action accepted, awaiting downstream confirmation
COMPLETED: Downstream backend confirmed the action
FAILED: Downstream backend reported a failure

Example: PENDINGPossible values:

PENDINGCOMPLETEDFAILED

conversationIdstring

Optional

The conversation this action belongs to.

Example: conv_conversation_01k1etx3jbfx88476ccja0889c

relatedobject

Optional

Named identifiers from downstream. For SEND_MESSAGE:

messageSid: The downstream message SID (present when PENDING or COMPLETED)
communicationId: The Communication ID (present when COMPLETED)

Example: {"messageSid":"SM1234567890abcdef1234567890abcdef","communicationId":"conv_communication_01k1etx3jbfx88476ccja0889c"}

Show related properties

createdAtstring<date-time>

Optional

Timestamp when the action was created.

Example: 2026-03-30T10:30:00Z

updatedAtstring<date-time>

Optional

Timestamp when the action was last updated.

Example: 2026-03-30T10:30:02Z

completedAtstring<date-time>

Optional

Timestamp when the action reached a terminal status.

Example: 2026-03-30T10:30:02Z

Get Action Status

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 fetchConversationAction() {
11  const action = await client.conversations.v2
12    .actions("ConversationId", "ActionId")
13    .fetch();
14
15  console.log(action.id);
16}
17
18fetchConversationAction();

Response

1{
2  "completedAt": "2009-07-06T20:30:00Z",
3  "conversationId": "conversationId",
4  "createdAt": "2009-07-06T20:30:00Z",
5  "id": "id",
6  "related": {},
7  "status": "PENDING",
8  "type": "type",
9  "updatedAt": "2009-07-06T20:30:00Z"
10}