Skip to main content
POST
Open a conversation

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

Body

application/json

Who receives the e-mail, what it says, and the key that makes a retry safe. Send exactly one of email or contact_id.

inbox_id
integer
required

The e-mail inbox the message leaves from: an id from List inboxes whose channel_type is Channel::Email.

Example:

12

subject
string
required

Subject of the e-mail. It also names the conversation for your agents.

Example:

"Your order 1042 has shipped"

content
string
required

Body of the e-mail, as text.

Example:

"Hello Maria, your order left our warehouse today and should arrive on Thursday."

email
string

Address that receives the message. The contact is created when your account has none with this address. Send this or contact_id, never both.

Example:

"maria.silva@example.com"

contact_id
integer

The id of an existing contact of your account, the same contact.id the conversation endpoints return. The message goes to the e-mail address stored on that contact. Send this or email, never both.

Example:

815

name
string

Display name for the contact. Used only when email creates a new contact: for an existing contact, or with contact_id, it changes nothing. Left out, the part of the address before the @ is used.

Example:

"Maria Silva"

cc_emails
string[]

Addresses in copy, visible to the recipient. A single comma-separated string is accepted too. Together with bcc_emails the call takes a limited number of addresses; over it the answer is 422 too_many_recipients and the message names the maximum. A malformed address is a 422 invalid_recipient.

Example:
bcc_emails
string[]

Addresses in blind copy, with the same rules and the same shared limit as cc_emails.

attachment_blob_ids
integer[]

Images already stored with Upload an image, by the blob_id it returned (PNG, JPEG or WEBP, up to 10 MB). An id that is not a file of your account is a 422 attachment_not_found naming it.

Example:
attachment_urls
string<uri>[]

Public https links that Cloud Chat downloads and attaches, for the documents the upload endpoint does not take: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT and CSV, up to 25 MB each. The download happens inside the call. A link that is private, too big or of another type is a 422 with attachment_url_unsafe, attachment_url_too_large, attachment_url_wrong_type, attachment_url_invalid or attachment_url_rejected. Together with attachment_blob_ids the call takes a limited number of attachments, and the answer when you go over is 422 too_many_attachments.

Example:
idempotency_key
string

Your own token for this message, up to 128 characters. Repeating a call with the same key and the same content returns the original conversation and sends nothing again. Send it on every call.

Example:

"order-1042-shipped"

Response

The conversation is open and the e-mail is queued, not yet delivered. A repeat with the same idempotency_key also answers 201, with dispatch_status duplicate.

The conversation that was opened, in the same projection Get a conversation returns, plus the outcome of the dispatch.

id
integer
required

The conversation number — the same one shown in the dashboard URL and delivered in webhooks, unique within the account.

Example:

1042

uuid
string
required

The conversation's canonical id, globally unique and never null — the same cloudChatId the ClaudIA API takes in Get a conversation summary and Get a message trace.

Example:

"495fd1e4-dbbb-46c6-8463-55cbf7b1d085"

status
enum<string>
required

Where the conversation is in its lifecycle.

Available options:
open,
resolved,
pending,
snoozed,
proactive
Example:

"open"

priority
enum<string> | null
required

The conversation's priority, null when none is set. One of the four levels the dashboard offers, in ascending urgency.

Available options:
low,
medium,
high,
urgent
Example:

"high"

assignee_id
integer | null
required

The agent currently assigned, null while unassigned.

Example:

7

inbox_id
integer
required

The inbox the conversation lives in.

Example:

3

team_id
integer | null
required

The team it is assigned to, null when none.

Example:

2

contact
object | null
required

The customer, null on the rare conversation without one.

labels
string[]
required

Labels applied to the conversation. Empty when it has none.

One label, exactly as it appears in the dashboard.

created_at
string<date-time>
required

When it was created. ISO 8601, always UTC, milliseconds included.

Example:

"2026-08-13T19:09:51.482Z"

updated_at
string<date-time>
required

When it last changed, in the same format. This is what updated_after / updated_before filter on.

Example:

"2026-08-13T19:42:07.115Z"

last_activity_at
string<date-time> | null
required

When the last message or activity happened. The list is ordered by this, newest first.

Example:

"2026-08-13T19:42:07.115Z"

custom_attributes
object | null
required

The account's custom conversation attributes, as configured in the dashboard. Keys and value types vary per account; an account with none defined answers {}.

Example:
snoozed_until
string<date-time> | null
required

When a snoozed conversation is scheduled to reopen. null outside the snoozed status.

Example:

null

waiting_since
string<date-time> | null
required

When the conversation started waiting on the customer's or the agent's next move — the field SLA and wait-time reports are built on. null when nothing is being waited on.

Example:

null

dispatch_status
enum<string>
required

What this call did: created when it opened the conversation and queued the e-mail, duplicate when the idempotency_key had already opened one and this is the original answer, with nothing sent again. The conversation's own state is in status.

Available options:
created,
duplicate
Example:

"created"

message_id
integer | null
required

The id of the first message of the conversation, the e-mail that was queued. On a duplicate, the one sent the first time. It is filled on every normal answer and null only when that message cannot be found.

Example:

90871