curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"inbox_id": 12,
"email": "maria.silva@example.com",
"name": "Maria Silva",
"subject": "Your order 1042 has shipped",
"content": "Hello Maria, your order left our warehouse today and should arrive on Thursday.",
"idempotency_key": "order-1042-shipped"
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations"
payload = {
"inbox_id": 12,
"email": "maria.silva@example.com",
"name": "Maria Silva",
"subject": "Your order 1042 has shipped",
"content": "Hello Maria, your order left our warehouse today and should arrive on Thursday.",
"idempotency_key": "order-1042-shipped"
}
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
inbox_id: 12,
email: 'maria.silva@example.com',
name: 'Maria Silva',
subject: 'Your order 1042 has shipped',
content: 'Hello Maria, your order left our warehouse today and should arrive on Thursday.',
idempotency_key: 'order-1042-shipped'
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'inbox_id' => 12,
'email' => 'maria.silva@example.com',
'name' => 'Maria Silva',
'subject' => 'Your order 1042 has shipped',
'content' => 'Hello Maria, your order left our warehouse today and should arrive on Thursday.',
'idempotency_key' => 'order-1042-shipped'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations"
payload := strings.NewReader("{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}"
response = http.request(request)
puts response.read_body{
"id": 1043,
"uuid": "9c1d5e0e-6a0c-4f0b-9a54-0d3a5c2f7b11",
"status": "open",
"priority": null,
"assignee_id": null,
"inbox_id": 12,
"team_id": null,
"contact": {
"id": 815,
"name": "Maria Silva"
},
"labels": [],
"custom_attributes": {},
"snoozed_until": null,
"waiting_since": null,
"created_at": "2026-11-09T19:12:03.114Z",
"updated_at": "2026-11-09T19:12:03.114Z",
"last_activity_at": "2026-11-09T19:12:03.114Z",
"dispatch_status": "created",
"message_id": 90871
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "inbox_id",
"code": "invalid",
"message": "The value must be a single scalar, not an array or object."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state of the resource.",
"details": [
{
"field": "idempotency_key",
"code": "idempotency_key_payload_mismatch",
"message": "This idempotency_key was already used for a different payload, so the new message was not sent. Send it with a new key, or resend the original payload to get the original conversation back."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "subject",
"code": "subject_required",
"message": "subject is required: it opens the mail thread and becomes the ticket title."
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Open a conversation
This call sends an e-mail to your customer, and it cannot be taken back. It opens a new conversation on one of your e-mail inboxes and sends content as its first message, with subject as the mail subject. Use it for one contact per call; to write to many contacts at once, use Create a campaign.
The inbox. It has to be an e-mail inbox your token reaches: every inbox of the account for an administrator, only the inboxes the agent is a member of otherwise. Any other inbox_id is a 422 inbox_not_assigned, whether or not the inbox exists. List inboxes shows each inbox’s channel_type, which has to be Channel::Email, and lock_to_single_conversation. The message leaves through the inbox’s own mail account, so the sender, signature and domain are the ones already configured there.
Only e-mail works today: an inbox of any other channel is a 422 unsupported_channel. An inbox with single-conversation mode on is a 422 inbox_locked_to_single_conversation, because the message would join the contact’s earlier thread and your subject would be dropped.
The recipient. Send exactly one of email or contact_id. With email, the contact is created when your account has none with that address; name only matters then. With contact_id, the contact has to be in your account and have an e-mail address, and the message goes to it. List contacts and Get a contact read contacts, and are for administrators; any member can send email.
Retries. Send an idempotency_key on every call: one value per message you mean to send, such as an order id plus the purpose. If a call times out or you lose the answer, repeat it with the same key and exactly the same content. You get the original conversation back with dispatch_status duplicate and the same message_id, and nothing is sent again. Without a key, a repeat opens a second conversation and sends a second e-mail. The same key with a different body, recipients, attachments or contact is a 409 and nothing is sent; use a new key for a new message. A key is remembered for a limited time and counts per inbox, so it protects retries, not a message you send again days later.
What a 201 means. The conversation and its first message exist and the e-mail is queued. Delivery happens afterwards: a later bounce does not come back through this call. An address that already hard bounced, was reported as spam, or bounced on this inbox is refused up front with 422 recipient_suppressed, and nothing is created. A 201 is also the answer to a duplicate.
Rate limit. Don’t hardcode it. Two ceilings apply: the gateway limits each credential, and Cloud Chat limits e-mail dispatch per account, shared by every credential of the account. Retry-After and the ratelimit-* headers carry the current values.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"inbox_id": 12,
"email": "maria.silva@example.com",
"name": "Maria Silva",
"subject": "Your order 1042 has shipped",
"content": "Hello Maria, your order left our warehouse today and should arrive on Thursday.",
"idempotency_key": "order-1042-shipped"
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations"
payload = {
"inbox_id": 12,
"email": "maria.silva@example.com",
"name": "Maria Silva",
"subject": "Your order 1042 has shipped",
"content": "Hello Maria, your order left our warehouse today and should arrive on Thursday.",
"idempotency_key": "order-1042-shipped"
}
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
inbox_id: 12,
email: 'maria.silva@example.com',
name: 'Maria Silva',
subject: 'Your order 1042 has shipped',
content: 'Hello Maria, your order left our warehouse today and should arrive on Thursday.',
idempotency_key: 'order-1042-shipped'
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'inbox_id' => 12,
'email' => 'maria.silva@example.com',
'name' => 'Maria Silva',
'subject' => 'Your order 1042 has shipped',
'content' => 'Hello Maria, your order left our warehouse today and should arrive on Thursday.',
'idempotency_key' => 'order-1042-shipped'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations"
payload := strings.NewReader("{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inbox_id\": 12,\n \"email\": \"maria.silva@example.com\",\n \"name\": \"Maria Silva\",\n \"subject\": \"Your order 1042 has shipped\",\n \"content\": \"Hello Maria, your order left our warehouse today and should arrive on Thursday.\",\n \"idempotency_key\": \"order-1042-shipped\"\n}"
response = http.request(request)
puts response.read_body{
"id": 1043,
"uuid": "9c1d5e0e-6a0c-4f0b-9a54-0d3a5c2f7b11",
"status": "open",
"priority": null,
"assignee_id": null,
"inbox_id": 12,
"team_id": null,
"contact": {
"id": 815,
"name": "Maria Silva"
},
"labels": [],
"custom_attributes": {},
"snoozed_until": null,
"waiting_since": null,
"created_at": "2026-11-09T19:12:03.114Z",
"updated_at": "2026-11-09T19:12:03.114Z",
"last_activity_at": "2026-11-09T19:12:03.114Z",
"dispatch_status": "created",
"message_id": 90871
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "inbox_id",
"code": "invalid",
"message": "The value must be a single scalar, not an array or object."
}
]
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "This account is suspended."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state of the resource.",
"details": [
{
"field": "idempotency_key",
"code": "idempotency_key_payload_mismatch",
"message": "This idempotency_key was already used for a different payload, so the new message was not sent. Send it with a new key, or resend the original payload to get the original conversation back."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "subject",
"code": "subject_required",
"message": "subject is required: it opens the mail thread and becomes the ticket title."
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Authorizations
Headers
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.
1
Path Parameters
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.
1
Body
Who receives the e-mail, what it says, and the key that makes a retry safe. Send exactly one of email or contact_id.
The e-mail inbox the message leaves from: an id from List inboxes whose channel_type is Channel::Email.
12
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.
["finance@example.com"]
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.
[5120]
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.
[
"https://files.example.com/invoices/1042.pdf"
]
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.
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.
"495fd1e4-dbbb-46c6-8463-55cbf7b1d085"
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.
created, duplicate "created"