---
title: "Create a new Conversation"
method: POST
path: "/v2/Conversations"
tags: ["ConversationsV2Conversation"]
---

# Create a new Conversation

`POST /v2/Conversations`

Create a new conversation

## Request body

- object
  - `configurationId` string, required — The ID of an existing configuration.
  - `name` string — The name of the conversation.
  - `configuration` object — Conversation configuration settings.
    - `intelligenceConfigurationIds` string[] — A list of Conversational Intelligence configuration IDs.
  - `participants` object[] — Optional list of Participants to create with the Conversation.
    - `name` string — Display name for the Participant.
    - `type` 'HUMAN_AGENT' | 'CUSTOMER' | 'AI_AGENT' — Type of Participant in the Conversation.
    - `profileId` string — Resolved profile ID.
    - `addresses` object[] — List of Communication addresses for the Participant.
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'EMAIL' | 'WHATSAPP' | 'CHAT' | 'API' | 'SYSTEM', required
      - `address` string, required
      - `channelId` string

## Response `201`

Created

- object
  - `id` string, required — Conversation ID.
  - `accountId` string, required — Account ID.
  - `configurationId` string, required — Configuration ID.
  - `status` 'ACTIVE' | 'INACTIVE' | 'CLOSED' — Conversation status.
  - `name` string, nullable — Conversation name.
  - `createdAt` string, date-time — Timestamp when this Conversation was created.
  - `updatedAt` string, date-time — Timestamp when this Conversation was last updated.
  - `configuration` object — Full configuration settings for this Conversation.
    - `displayName` string — A human-readable name for the configuration. Limited to 32 characters.
    - `description` string — Human-readable description for the Configuration.
    - `conversationGroupingType` 'GROUP_BY_PROFILE' | 'GROUP_BY_PARTICIPANT_ADDRESSES' | 'GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE' — Type of Conversation grouping strategy: - `GROUP_BY_PROFILE`: Groups Communications by resolved Profile from the Memory Store. A Profile is looked up or created for `CUSTOMER` Participant types. All Communications from the same Profile are in the same Conversation, regardless of address or channel. - `GROUP_BY_PARTICIPANT_ADDRESSES`: Groups Communications by Participant addresses across all channels. A customer using +18005550100 will be in the same Conversation whether they contact by SMS, WhatsApp, or RCS. - `GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE`: Groups Communications by both Participant addresses AND channel. A customer using +18005550100 by SMS will be in a different Conversation than the same customer by Voice.
    - `memoryStoreId` string — Memory Store ID for Profile resolution.
    - `channelSettings` ConversationsV2ChannelSettings — Channel-specific parameters forwarded as-is to the downstream sending service. Allows passing backend-specific fields without requiring API changes.
    - `statusCallbacks` ConversationsV2StatusCallbackConfig[] — List of default webhook configurations applied to Conversations under this Configuration.
      - `url` string, uri, required — Destination URL for webhooks.
      - `method` 'POST' | 'GET' — HTTP method used to invoke the webhook URL.
    - `intelligenceConfigurationIds` string[] — List of Intelligence Configuration IDs configured for this Configuration.
    - `memoryExtractionEnabled` boolean — Whether memory extraction is enabled for conversations under this configuration. Defaults to false.
    - `conversationsV1Bridge` ConversationsV2ConversationsV1Bridge — Configuration for Conversations V1 bridge. When set, messaging channels route through Conversations V1. Use this to integrate with existing Conversations V1 applications.
      - `serviceId` string, required — The Conversations V1 Service SID (IS prefix). One configuration per V1 Service SID.
  - `participants` ConversationsV2Participant[] — Participants in this Conversation.
    - `id` string, required — Participant ID.
    - `conversationId` string, required — Conversation ID.
    - `accountId` string, required — Account ID.
    - `name` string, required — Participant display name.
    - `type` 'HUMAN_AGENT' | 'CUSTOMER' | 'AI_AGENT' | 'AGENT' | 'UNKNOWN' — Type of Participant in the Conversation.
    - `profileId` string — Profile ID. Note: This field is only resolved for `CUSTOMER` participant types, not for `HUMAN_AGENT` or `AI_AGENT` participants.
    - `addresses` ConversationsV2Address[] — Communication addresses for this Participant. Address format varies by channel: - SMS/VOICE: E.164 phone number (such as "+18005550100") - EMAIL: Email address (such as "user@example.com") - WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100") - RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100")
      - `channel` 'VOICE' | 'SMS' | 'RCS' | 'WHATSAPP' | 'CHAT', required — The channel for Communication.
      - `address` string, required — The address value formatted according to channel type: - SMS/VOICE: E.164 phone number (such as "+18005550100") - WHATSAPP: Phone number with whatsapp prefix (such as "whatsapp:+18005550100") - RCS: Sender ID or phone number with rcs prefix (such as "rcs:brand_acme_agent" or "rcs:+18005550100") - CHAT: Customer-defined string identifier
      - `channelId` string — Channel-specific ID for correlating Communications.
    - `createdAt` string, date-time — Timestamp when this Participant was created.
    - `updatedAt` string, date-time — Timestamp when this Participant was last updated.

## Other responses

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

---

[API](https://skmtc.net/twilio/apis/conversations-v2.md) · [All operations](https://skmtc.net/twilio/apis/conversations-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twilio/conversations-v2/versions/88b1cc30ae5b/schema)