v2

latestOpenAPI 3.0.1raw.githubusercontent.com2026-05-072126235.6 KB

ConversationsV2Action

Create an Action

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.

post/v2/Conversations/{ConversationId}/Actions

Request body

typestring required

Action type discriminator. Accepted values: SEND_MESSAGE.

Example request

{
  "type": "SEND_MESSAGE",
  "payload": {
    "from": {
      "participantId": "conv_participant_01k1etx3jbfx88476ccja0889e",
      "address": "+15551234567"
    },
    "to": [
      {
        "participantId": "conv_participant_01k1etx3jbfx88476ccja0889e",
        "address": "+15551234567"
      }
    ],
    "content": {
      "text": "Your order has shipped!",
      "contentId": "HX78e8e67abc123def456789012345678",
      "variables": {
        "name": "Alice",
        "orderNumber": "12345"
      },
      "mediaUrls": [
        "https://example.com/image.jpg"
      ]
    },
    "channelSettings": {
      "messagingServiceSid": "MG1234567890abcdef1234567890abcdef",
      "statusCallback": "https://example.com/status"
    }
  }
}

Response

Action accepted. Returns the Action in PENDING status.

idstring required

Unique identifier for this Action.

typestring required

The type of action. Accepted values: SEND_MESSAGE.

status'PENDING' | 'COMPLETED' | 'FAILED' required

Current status of the Action.

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

conversationIdstring required

The conversation this action belongs to.

relatedobject

Named identifiers from downstream. For SEND_MESSAGE:

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

createdAtstring date-time required

Timestamp when the action was created.

updatedAtstring date-time

Timestamp when the action was last updated.

completedAtstring date-time

Timestamp when the action reached a terminal status.

Example response

{
  "id": "conv_action_01k1etx3jbfx88476ccja0889e",
  "type": "SEND_MESSAGE",
  "status": "COMPLETED",
  "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c",
  "related": {
    "messageSid": "SM1234567890abcdef1234567890abcdef",
    "communicationId": "conv_communication_01k1etx3jbfx88476ccja0889c"
  },
  "createdAt": "2026-03-30T10:30:00Z",
  "completedAt": "2026-03-30T10:30:02Z"
}