curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"status": "snoozed",
"snoozed_until": "2026-12-01T09:00:00Z"
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status"
payload = {
"status": "snoozed",
"snoozed_until": "2026-12-01T09:00:00Z"
}
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({status: 'snoozed', snoozed_until: '2026-12-01T09:00:00Z'})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status', 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/{conversationId}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'status' => 'snoozed',
'snoozed_until' => '2026-12-01T09:00:00Z'
]),
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/{conversationId}/status"
payload := strings.NewReader("{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"id": 1042,
"uuid": "495fd1e4-dbbb-46c6-8463-55cbf7b1d085",
"status": "open",
"priority": "high",
"assignee_id": 7,
"inbox_id": 3,
"team_id": 2,
"contact": {
"id": 815,
"name": "Jane"
},
"labels": [
"vip"
],
"created_at": "2026-08-13T19:09:51.482Z",
"updated_at": "2026-08-13T19:42:07.115Z",
"last_activity_at": "2026-08-13T19:42:07.115Z",
"custom_attributes": {
"order_id": "A-1029"
},
"snoozed_until": null,
"waiting_since": null
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "status",
"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": "You are not allowed to perform this action."
}
}{
"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": "conversation",
"code": "merged",
"message": "This conversation was merged into another one and is read-only. Work on the conversation it was merged into."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "This account requires fields to be filled before a conversation can be resolved. The details list each missing field.",
"details": [
{
"field": "priority",
"code": "required",
"message": "Set a priority with the update conversation endpoint, then resolve again."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "The reporting service is temporarily unavailable. Try again in a few minutes.",
"details": [
{
"field": "conversation",
"code": "handoff_failed",
"message": "The conversation could not be taken over from ClaudIA right now and was not reassigned. Try again in a few minutes."
}
]
}
}Change the status of a conversation
Move a conversation to an explicit status: open (also how a resolved conversation is reopened), resolved, pending or snoozed. There is no toggle — you say the status you want, and asking for the status the conversation already has succeeds without changing anything, the assignee included.
For snoozed, snoozed_until is an optional ISO 8601 instant in the future when the conversation should come back. Omit it to snooze until the customer’s next reply (snoozing again without it clears a wake-up time set earlier); sending it with any other status is a 422.
The dashboard rules apply, and each refusal says how to fix it:
- a conversation merged into another one is read-only — a 409;
- a parent conversation cannot be resolved while its parallel conversations are still open — a 409 whose message lists them;
- an account that requires fields before a conversation can be resolved answers 422 with one entry in
error.detailsper missing field.
Reopening a conversation that was not open (resolved, pending or snoozed) with an agent token assigns it to that agent, as the dashboard does; tokens of other roles are not assigned, and a conversation that is already open keeps its assignee. When ClaudIA holds the conversation, that assignment follows the account’s takeover permissions, like the assign endpoint: a role that may not take over gets a 403 and nothing changes, and when ClaudIA cannot be reached the answer is a 503 (409 if a transfer is already in progress) and the conversation stays reopened but not reassigned, so retry the handover with the assign endpoint. Resolving can make Cloud Chat send the customer the satisfaction survey when the inbox has it enabled, and that message cannot be undone. Visibility follows the same rule as the list: an administrator token reaches every inbox of the account, an agent token only its own inbox memberships. A conversation outside that reach answers 404, indistinguishable from an id that does not exist. A conversation mirrored from another helpdesk is read-only here and answers 409.
curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"status": "snoozed",
"snoozed_until": "2026-12-01T09:00:00Z"
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status"
payload = {
"status": "snoozed",
"snoozed_until": "2026-12-01T09:00:00Z"
}
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({status: 'snoozed', snoozed_until: '2026-12-01T09:00:00Z'})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status', 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/{conversationId}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'status' => 'snoozed',
'snoozed_until' => '2026-12-01T09:00:00Z'
]),
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/{conversationId}/status"
payload := strings.NewReader("{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-12-01T09:00:00Z\"\n}"
response = http.request(request)
puts response.read_body{
"id": 1042,
"uuid": "495fd1e4-dbbb-46c6-8463-55cbf7b1d085",
"status": "open",
"priority": "high",
"assignee_id": 7,
"inbox_id": 3,
"team_id": 2,
"contact": {
"id": 815,
"name": "Jane"
},
"labels": [
"vip"
],
"created_at": "2026-08-13T19:09:51.482Z",
"updated_at": "2026-08-13T19:42:07.115Z",
"last_activity_at": "2026-08-13T19:42:07.115Z",
"custom_attributes": {
"order_id": "A-1029"
},
"snoozed_until": null,
"waiting_since": null
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "status",
"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": "You are not allowed to perform this action."
}
}{
"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": "conversation",
"code": "merged",
"message": "This conversation was merged into another one and is read-only. Work on the conversation it was merged into."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "This account requires fields to be filled before a conversation can be resolved. The details list each missing field.",
"details": [
{
"field": "priority",
"code": "required",
"message": "Set a priority with the update conversation endpoint, then resolve again."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "The reporting service is temporarily unavailable. Try again in a few minutes.",
"details": [
{
"field": "conversation",
"code": "handoff_failed",
"message": "The conversation could not be taken over from ClaudIA right now and was not reassigned. Try again in a few minutes."
}
]
}
}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
The conversation's display_id — the number shown in the dashboard URL and delivered in webhooks. It is never the internal database id, and it is never the conversation's uuid: when all you have is a uuid or a helpdesk ticket id, resolve it to a display_id with Find a conversation first.
1042
Body
The status to move the conversation to.
Status to move the conversation to. open also reopens a resolved, pending or snoozed conversation and, for an agent token, assigns it to that agent; on a conversation that is already open it changes nothing. There is no toggle: the conversation ends up in exactly this status.
open, resolved, pending, snoozed "resolved"
Response
The conversation after the change.
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"