curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"assignment": {
"assignee_id": 7,
"team_id": 2
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments"
payload = { "assignment": {
"assignee_id": 7,
"team_id": 2
} }
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({assignment: {assignee_id: 7, team_id: 2}})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments', 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}/assignments",
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([
'assignment' => [
'assignee_id' => 7,
'team_id' => 2
]
]),
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}/assignments"
payload := strings.NewReader("{\n \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\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/{conversationId}/assignments")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments")
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 \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\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": "Provide at least one of assignee_id or team_id. Send null to remove the current assignee or team."
}
}{
"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": "external_read_only",
"message": "This conversation is mirrored from another helpdesk and is read-only in Cloud Chat. Make the change in the system where it originates."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "assignee_id",
"code": "invalid",
"message": "No active agent with this id in this account. List the agents and use the id they return."
}
]
}
}{
"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."
}
]
}
}Assign a conversation
This is the endpoint for taking a conversation away from ClaudIA and handing it to a person, yourself included: assign the conversation to a human agent while ClaudIA holds it and ClaudIA is told to step aside. To take it yourself, send your own agent id as assignee_id; find it with List agents by searching for your own e-mail. It also assigns a conversation to an agent, to a team, or to both. The targets go under an assignment wrapper: assignee_id (an id from List agents) and team_id (an id from List teams). Send null for one of them to remove the current agent or team, and leave the key out to keep it as it is. At least one of the two is required.
Ids must belong to this account: an id that is not an active agent of the account, or a team of another account, is a 422 and the message says which list to read again. ClaudIA agents cannot be assigned through this endpoint; hand a conversation back to ClaudIA from the Cloud Chat screen.
That takeover — assigning a person, or a team that does not include ClaudIA, while ClaudIA holds the conversation — follows the account’s takeover permissions. A role that may not take over gets a 403 and nothing changes. When ClaudIA cannot be reached the answer is 503 and the conversation stays as it was.
When both keys are sent the team is applied first, so a failure on the agent leaves the team already changed. 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 POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"assignment": {
"assignee_id": 7,
"team_id": 2
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments"
payload = { "assignment": {
"assignee_id": 7,
"team_id": 2
} }
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({assignment: {assignee_id: 7, team_id: 2}})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments', 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}/assignments",
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([
'assignment' => [
'assignee_id' => 7,
'team_id' => 2
]
]),
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}/assignments"
payload := strings.NewReader("{\n \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\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/{conversationId}/assignments")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/assignments")
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 \"assignment\": {\n \"assignee_id\": 7,\n \"team_id\": 2\n }\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": "Provide at least one of assignee_id or team_id. Send null to remove the current assignee or team."
}
}{
"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": "external_read_only",
"message": "This conversation is mirrored from another helpdesk and is read-only in Cloud Chat. Make the change in the system where it originates."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "assignee_id",
"code": "invalid",
"message": "No active agent with this id in this account. List the agents and use the id they return."
}
]
}
}{
"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
Response
The conversation after the assignment.
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"