Home API and integrations | Keys, endpoints and webhooks Updating Custom Attributes in Conversations via API

Updating Custom Attributes in Conversations via API

Last updated on Oct 21, 2025

To update custom attributes in conversations via API in Cloud Chat, simply send a PUT request to:

https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes

Make sure to include the access key (API_TOKEN) in the headers and follow the requested fields as described below.

Example request with fields:

curl --request PUT \
  --url https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes \
  --header 'api_access_token: API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "custom_attributes": {
    "to_be_updated": "new_value",
	"to_be_removed": null
  }
}'

Request Body

The request must contain a single field, custom_attributes, which should be an object with the attributes to be updated.

Note:
The conversation_id of the conversation to be updated must not be included in the request body, as it is passed as a URL parameter.

Example Request:

PUT /conversations/123/custom_attributes
{
  "custom_attributes": {
    "to_be_updated": "new_value",
	"to_be_removed": null
  }
}

Attribute Types

Custom conversation attributes have a predefined value type, set in their configuration, which must be respected when using the endpoint to update values:

  • Text: Must accept String values.

  • Number: Must contain only digits. Alphabetic or special characters are not allowed.

  • Link: Must be a valid URL (http or https). The link must end with a valid domain (e.g., .com, .net, .org).

  • Date: Must be in ISO8601 format (YYYY-MM-DDTHH:MM:SS.sssZ). Valid example: "2025-01-01T12:00:00.000Z".

  • List: Must be a String value, and this value must be among the options defined in the attribute configuration.

  • Checkbox: Must be either "true" / "false" (string), or true / false (Boolean).

Note:
To remove a value assigned to a custom attribute, simply send null or an empty string (""). The system will process the request and remove the attribute from the custom_attributes object, ensuring it is no longer present in the conversation.

Error Handling

If any value sent in the custom_attributes field does not comply with the rules, the request will not be processed and a specific error will be returned:

  • If the conversation is not found, the system returns an error "Conversation not found" with status code 404.

  • If the request body is incorrect, an error "Invalid attributes" with status code 422 will be returned.

  • If an attribute does not exist in the configuration, an error indicating that the attribute was not found will be returned.

  • If a value does not match the expected type, a message will be returned indicating the issue, such as: "number_attr must contain only numeric digits" or "date_attr must be in ISO8601 format (YYYY-MM-DDTHH:MM:SS.sssZ)".