curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"labels": [
"refund",
"vip"
]
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels"
payload = { "labels": ["refund", "vip"] }
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({labels: ['refund', 'vip']})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels', 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}/labels",
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([
'labels' => [
'refund',
'vip'
]
]),
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}/labels"
payload := strings.NewReader("{\n \"labels\": [\n \"refund\",\n \"vip\"\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}/labels")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"labels\": [\n \"refund\",\n \"vip\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels")
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 \"labels\": [\n \"refund\",\n \"vip\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"labels": [
"vip",
"refund"
],
"added": [
"refund"
]
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "labels",
"code": "invalid_shape",
"message": "labels must be a list of label titles, each one a non-empty text."
}
]
}
}{
"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": "conversation",
"code": "external_read_only",
"message": "Conversations mirrored from another helpdesk or from ClaudIA are read-only: their labels belong to the source system."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "labels",
"code": "unknown_label",
"message": "There is no label \"ghost\" in this account. List the account labels with listLabels, or create it with createLabel, before applying it."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Add labels to a conversation
Adds labels to one conversation and keeps the ones it already has. Send labels as a list of label titles; every one has to exist on the account already, because this call never creates a label on the fly: find them with List labels or create one with Create a label first.
Titles are matched the way labels are stored, trimmed and case-insensitive. A label the conversation already carries is skipped without error, and added in the response lists the ones that were really applied, so repeating the call is safe. If any title is unknown, nothing is applied and the answer is 422.
Labelling a conversation can fire the account’s automation rules that react to conversation updates, and it leaves an activity note in the conversation.
What you can reach follows the dashboard rule: an administrator token reaches every inbox, an agent token only the inboxes it is a member of, and a conversation outside that reach answers 404, the same as a display id that does not exist. Conversations mirrored from ClaudIA or from another helpdesk are read-only for labels: they answer 409, because their labels belong to the source system. Any member of the account can label a conversation they can reach.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"labels": [
"refund",
"vip"
]
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels"
payload = { "labels": ["refund", "vip"] }
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({labels: ['refund', 'vip']})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels', 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}/labels",
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([
'labels' => [
'refund',
'vip'
]
]),
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}/labels"
payload := strings.NewReader("{\n \"labels\": [\n \"refund\",\n \"vip\"\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}/labels")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"labels\": [\n \"refund\",\n \"vip\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/conversations/{conversationId}/labels")
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 \"labels\": [\n \"refund\",\n \"vip\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"labels": [
"vip",
"refund"
],
"added": [
"refund"
]
}{
"error": {
"code": "bad_request",
"message": "The request is malformed.",
"details": [
{
"field": "labels",
"code": "invalid_shape",
"message": "labels must be a list of label titles, each one a non-empty text."
}
]
}
}{
"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": "conversation",
"code": "external_read_only",
"message": "Conversations mirrored from another helpdesk or from ClaudIA are read-only: their labels belong to the source system."
}
]
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "labels",
"code": "unknown_label",
"message": "There is no label \"ghost\" in this account. List the account labels with listLabels, or create it with createLabel, before applying it."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"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
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 labels to apply, as titles. Every title has to be a label of the account already.
Response
The labels the conversation carries now, and which of the requested ones were newly applied.