curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_attribute": {
"name": "Plan",
"description": "Plan the customer subscribed to.",
"values": [
"free",
"pro",
"team",
"enterprise"
],
"required": true
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}"
payload = { "custom_attribute": {
"name": "Plan",
"description": "Plan the customer subscribed to.",
"values": ["free", "pro", "team", "enterprise"],
"required": True
} }
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({
custom_attribute: {
name: 'Plan',
description: 'Plan the customer subscribed to.',
values: ['free', 'pro', 'team', 'enterprise'],
required: true
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}', 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}/custom-attributes/{customAttributeId}",
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([
'custom_attribute' => [
'name' => 'Plan',
'description' => 'Plan the customer subscribed to.',
'values' => [
'free',
'pro',
'team',
'enterprise'
],
'required' => true
]
]),
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}/custom-attributes/{customAttributeId}"
payload := strings.NewReader("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\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}/custom-attributes/{customAttributeId}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}")
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 \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 42,
"key": "plan",
"name": "Plan",
"description": "Plan the customer subscribed to.",
"type": "list",
"model": "contact",
"values": [
"free",
"pro",
"enterprise"
],
"required": false,
"regex_pattern": "/^[0-9]{11}$/",
"regex_cue": "Only the 11 digits of the CPF.",
"conditional": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-05-02T11:04:17.000Z"
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"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": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "key",
"code": "not_editable",
"message": "The key cannot be changed after the attribute is created: values already saved on conversations, contacts and companies are stored under the key and read according to the type and model. Create a new attribute instead."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Update a custom attribute
Administrator only. Edits one custom attribute definition. The changes go under custom_attribute: send only what you mean to change.
Editable: name, description, values (the options of a list or multi_list; the whole list is replaced), required, and the regex that validates typed text (regex_pattern, regex_cue).
Never editable: the key, the type and the model. The values already stored on contacts, conversations and companies are kept under that key and read according to that type and model, so sending a different one answers 422. Sending the current one is accepted. To change one of them, create a new attribute with createCustomAttribute.
Taking an option off a list does not erase it from the contacts, conversations or companies that already carry it: they keep the stored value, which just stops being offered. An option that another field uses as its display condition cannot be taken off; the request answers 422 and nothing changes.
Changing required changes what Cloud Chat demands: a required conversation attribute has to be filled before a conversation can be resolved, while the field is shown. Turning it on can block conversations that could be closed a moment ago.
What else changes: editing the name, the options or the regex of a conversation or contact attribute also updates the same field in the pre-chat form of the account’s website chat widgets, as editing it in the Cloud Chat screen does. A company attribute can only be edited on an account that has companies enabled.
Not accepted here: AI field filling (ai_field_filling_enable, ai_fill_instruction, ai_fill_confidence_threshold) and any field outside the request schema. An administrator sets AI filling up in the Cloud Chat screen, and the request answers 400 with the field named in details.
curl --request PATCH \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"custom_attribute": {
"name": "Plan",
"description": "Plan the customer subscribed to.",
"values": [
"free",
"pro",
"team",
"enterprise"
],
"required": true
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}"
payload = { "custom_attribute": {
"name": "Plan",
"description": "Plan the customer subscribed to.",
"values": ["free", "pro", "team", "enterprise"],
"required": True
} }
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({
custom_attribute: {
name: 'Plan',
description: 'Plan the customer subscribed to.',
values: ['free', 'pro', 'team', 'enterprise'],
required: true
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}', 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}/custom-attributes/{customAttributeId}",
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([
'custom_attribute' => [
'name' => 'Plan',
'description' => 'Plan the customer subscribed to.',
'values' => [
'free',
'pro',
'team',
'enterprise'
],
'required' => true
]
]),
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}/custom-attributes/{customAttributeId}"
payload := strings.NewReader("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\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}/custom-attributes/{customAttributeId}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/custom-attributes/{customAttributeId}")
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 \"custom_attribute\": {\n \"name\": \"Plan\",\n \"description\": \"Plan the customer subscribed to.\",\n \"values\": [\n \"free\",\n \"pro\",\n \"team\",\n \"enterprise\"\n ],\n \"required\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 42,
"key": "plan",
"name": "Plan",
"description": "Plan the customer subscribed to.",
"type": "list",
"model": "contact",
"values": [
"free",
"pro",
"enterprise"
],
"required": false,
"regex_pattern": "/^[0-9]{11}$/",
"regex_cue": "Only the 11 digits of the CPF.",
"conditional": false,
"created_at": "2026-05-02T11:04:17.000Z",
"updated_at": "2026-05-02T11:04:17.000Z"
}{
"error": {
"code": "not_found",
"message": "Resource could not be found.",
"details": [
{
"field": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}{
"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": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "key",
"code": "not_editable",
"message": "The key cannot be changed after the attribute is created: values already saved on conversations, contacts and companies are stored under the key and read according to the type and model. Create a new attribute instead."
}
]
}
}{
"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
Body
The fields to change, under custom_attribute. Administrator only. Send at least one field; anything you leave out keeps its value. The current key, type and model are tolerated unchanged, so the answer of getCustomAttribute can be sent back with a field edited. Every other field outside this schema, including every AI fill field, answers 400.
Response
The definition as stored, after the change.
One custom attribute definition: a field the account added to conversations, contacts or companies. The AI fill settings and visibility rules are not part of this view.
Kind of value the field holds: text, number, currency, percent, link, date, list (one of the options in values), checkbox or multi_list (several of the options in values).
text, number, currency, percent, link, date, list, checkbox, multi_list "list"
Pattern the text typed into this field has to match, as a plain pattern or a /pattern/flags literal. Cloud Chat enforces it on company values and on the screen and the website chat form; a contact or conversation value written through this API is not checked against it. null when there is none.
"/^[0-9]{11}$/"