---
title: "Create an Action"
method: POST
path: "/v2/Conversations/{ConversationId}/Actions"
tags: ["ConversationsV2Action"]
---

# Create an Action

`POST /v2/Conversations/{ConversationId}/Actions`

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 body

- object
  - `type` string, required — Action type discriminator. Accepted values: SEND_MESSAGE.
  - `payload` ConversationsV2SendMessagePayload, required
    - `from` ConversationsV2SendMessageParticipant, required — Identifies a participant for an Action. Supports three resolution modes: 1. participantId + channel: Resolves address from participant's registered addresses 2. participantId only: Resolves when participant has exactly one address 3. address + channel: Uses explicit address
      - `participantId` string — Participant ID to resolve address from.
      - `address` string — Explicit address formatted according to channel type.
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'WHATSAPP' | 'CHAT' — Channel type for a Communication address.
    - `to` ConversationsV2SendMessageParticipant[], required — The recipients of this action.
      - `participantId` string — Participant ID to resolve address from.
      - `address` string — Explicit address formatted according to channel type.
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'WHATSAPP' | 'CHAT' — Channel type for a Communication address.
    - `content` ConversationsV2SendMessageContent, required — Content for a SEND_MESSAGE action.
      - `text` string — Plain text message body.
      - `contentId` string — Content template ID (HX... format). When provided, the template is rendered with the variables map and sent to the recipient.
      - `variables` object — Variables to substitute into the content template.
      - `mediaUrls` string[] — URLs of media attachments to include with the message.
    - `channelSettings` ConversationsV2ChannelSettings — Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.

## Response `202`

Action accepted. Returns the Action in PENDING status.

- object
  - `id` string, required — Unique identifier for this Action.
  - `type` string, required — The type of action. Accepted values: SEND_MESSAGE.
  - `status` 'PENDING' | 'COMPLETED' | 'FAILED', required — Lifecycle status of an Action.
  - `conversationId` string, required — The conversation this action belongs to.
  - `related` object — Named identifiers from downstream. For SEND_MESSAGE: - messageSid: The downstream message SID (present when PENDING or COMPLETED) - communicationId: The Communication ID (present when COMPLETED)
  - `createdAt` string, date-time, required — Timestamp when the action was created.
  - `updatedAt` string, date-time — Timestamp when the action was last updated.
  - `completedAt` string, date-time — Timestamp when the action reached a terminal status.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

## Changes

- **2026-05-07** (v2) `88b1cc30ae5b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/twilio/apis/conversations-v2/changes/v2/Conversations/:ConversationId/Actions/post.md)

---

[API](https://skmtc.dev/twilio/apis/conversations-v2.md) · [All operations](https://skmtc.dev/twilio/apis/conversations-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/twilio/conversations-v2/revisions/f039dce07916/schema)