How to update and act on tickets via API

The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this article and the reference differ, the reference prevails.

When to use

You want to change a ticket's status (resolve, reopen), priority, or team through an integration
You need to send messages automatically in an existing ticket
You need to manage labels on tickets

Prerequisites

An administrator or supervisor API Key — see How to find your API Key in Cloud Chat
CLOUDCHAT_DOMAIN, ACCOUNT_ID, CONVERSATION_ID (internal ID) and/or DISPLAY_ID (the ID visible in the UI)

These APIs write to production. Changes impact SLAs, metrics, and your operation. Validate the ticket's current state before making changes and test in a controlled environment before using in production.

About this article

These APIs let you modify real ticket data — change status, priority, team, and send messages. To only query data (without changing anything), use How to query contacts, tickets, and messages in real time via API.

Authentication

All endpoints require:

Header	Value
`content-type`	`application/json`
`api_access_token`	Administrator or supervisor token

1. Change ticket status (resolve, reopen, etc.)

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status

Body

{
  "status": "resolved"
}

Accepted values

Value	Description
`open`	Reopen ticket
`resolved`	Resolve ticket
`pending`	Mark as pending

Example

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"status": "resolved"}'

Returns the updated conversation object with status 200 OK.

The PUT /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} endpoint does not change the status — it only accepts the priority field. To change status, always use the toggle_status endpoint above.

2. Change ticket priority

Endpoint

PUT https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}

Body

{
  "priority": "high"
}

Accepted values

Value	Description
`nil` / `null`	No priority
`low`	Low
`medium`	Medium
`high`	High
`urgent`	Urgent

Example

curl -X PUT \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"priority": "high"}'

This endpoint (PUT .../conversations/{ID}) accepts only the priority field. Fields such as status, team_id, or others are silently ignored.

3. Change status, priority, and team (Client API)

To change status, priority, and/or team in a single call, use the Client API:

Endpoint

PATCH https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}

This endpoint uses the display_id (the ID visible in Cloud Chat), not the internal conversation_id.

This Client API requires an administrator token. Supervisor or agent tokens receive 403 Forbidden. If you use a supervisor token, change status via toggle_status (section 1) and priority via the PUT (section 2).

Body

{
  "status": "resolved",
  "priority": "high",
  "team_id": "1"
}

Accepted fields

Field	Description
`status`	Ticket status (`open`, `resolved`, `pending`)
`priority`	Priority (`low`, `medium`, `high`, `urgent`)
`team_id`	ID of the team for reassignment

All fields are optional — send only what you want to change.

If the provided team_id does not exist in the account, the API returns 422 with {"error": "Team not found"}.

Example

curl -X PATCH \
  'https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"status": "resolved"}'

4. Create a message in a ticket

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages

Body

{
  "content": "Olá! Segue atualização sobre sua solicitação.",
  "message_type": "outgoing"
}

Fields

Field	Required	Description
`content`	Yes	Message content
`message_type`	Yes	`incoming` (message from the customer) or `outgoing` (message from the agent/system)
`private`	No	`true` for an internal note (not visible to the customer)

Example

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "content": "Sua solicitação foi processada.",
    "message_type": "outgoing"
  }'

5. Manage labels on a ticket

The PUT /conversations/{ID} endpoint does not accept the labels field. If you send labels in the PUT body, the API returns 200 but silently ignores the field. To manage labels, use the dedicated endpoint below.

Endpoint

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Body

{
  "labels": ["suporte", "prioridade-alta"],
  "append": true
}

Fields

Field	Type	Required	Description
`labels`	array of strings	Yes	List of labels to apply
`append`	boolean	No	`true` adds to the existing labels. `false` or omitted replaces all of them

Example

curl -X POST \
  'https://cloudchat.cloudhumans.com/api/v1/accounts/1/conversations/12345/labels' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"labels": ["suporte", "urgente"], "append": true}'

Fields that cannot be changed via PUT/PATCH

Some fields look editable but are silently ignored by the API (it returns 200 with no error):

Field	Situation	What to do
`mail_subject`	Attribute inside `additional_attributes`. Can only be set when the ticket is created. Update attempts via PUT are ignored	There is no workaround via API. If the email subject needs to be different, create a new ticket
`labels`	Ignored in the ticket PUT/PATCH	Use the dedicated endpoint `POST .../conversations/{ID}/labels` (section 5)

Summary: which endpoint to use for each action

Desired action	Endpoint	Method
Change status (resolve, reopen)	`.../conversations/{ID}/toggle_status`	`POST`
Change priority	`.../conversations/{ID}`	`PUT`
Change status + priority + team	`/api/client/.../conversations/{DISPLAY_ID}`	`PATCH`
Create a message in the ticket	`.../conversations/{ID}/messages`	`POST`
Manage labels	`.../conversations/{ID}/labels`	`POST`

Recommended safe flow

Query the ticket's current state before changing it — see How to query contacts, tickets, and messages in real time via API
Validate whether the action is necessary (e.g., do not resolve a ticket that is already resolved)
Execute the change using the correct endpoint from the table above
Confirm the result by checking the API response

Where to find the parameters

CLOUDCHAT_DOMAIN — domain visible in the browser URL
ACCOUNT_ID — in Account Settings
CONVERSATION_ID — internal conversation ID (returned by the query APIs)
DISPLAY_ID — ID visible in the Cloud Chat interface (used only in the Client API)
API_TOKEN — at https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Notes

To create new tickets via API: How to create tickets via API in Cloud Chat
To update custom attributes on conversations: How to update custom attributes on conversations via API
To query without changing data: How to query contacts, tickets, and messages in real time via API
Overview of the available APIs: Master Guide — How to access and operate Cloud Chat data via API