Create conversation.

POST/api/v1/conversations

Browse API endpoints

Conversations / CRM REST API

Scope: conversations:write

Request body:

Code example

{
  "contactId": "contact_id_here",
  "channel": "email",
  "subject": "Welcome to our service"
}

Field	Required	Description
`contactId`	Yes	Contact to associate the conversation with
`channel`	Yes	`sms`, `email`, `messenger`, `instagram`, `gmail`, `live_chat`, `social_dm`
`subject`	No	Subject line (email only)

Response:

201 Created - New conversation created. Response includes "created": true.
200 OK - An existing open conversation was found for this contact and channel. Response includes "created": false. For sms, this is the contact's one conversation for calls and texts, reopened if it was closed, so an integration does not start a second thread beside it.

Code example

{
  "data": {
    "id": "conv_xyz789",
    "contactId": "contact_id_here",
    "channel": "email",
    "status": "open",
    "created": true
  }
}

Loading endpoint details...

Build a request

Request example

Documented defaults and example values are ready. Change only the parameters you need.

Connection

Your CRM deployment URL

Replace the Bearer API key placeholder in the copied server-side code. No API key is entered or sent here.

Sub-account ID Agency keys onlyAgency-scoped keys require the X-Sub-Account-Id header.

Body parameters

contactId Required - Contact to associate the conversation with

channel Required - sms, email, messenger, instagram, gmail, live_chat, social_dm

subject - Subject line (email only)

Edit the full JSON body

cURL

curl --request POST \
  --url 'https://your-crm.example.com/api/v1/conversations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"contactId":"contact_id_here","channel":"email","subject":"Welcome to our service"}'

This shows a static response from the documentation. It does not send a request to your CRM or use an API key.