Como atualizar e agir em tickets via API

Quando usar

Você quer alterar status (resolver, reabrir), prioridade ou time de um ticket via integração
Você precisa enviar mensagens automaticamente em um ticket existente
Você precisa gerenciar labels (etiquetas) em tickets

Pré-requisitos

API Key de administrador ou supervisor — ver Como encontrar sua API Key no Cloud Chat
CLOUDCHAT_DOMAIN, ACCOUNT_ID, CONVERSATION_ID (ID interno) e/ou DISPLAY_ID (ID visível na UI)

Estas APIs escrevem em produção. Alterações impactam SLAs, métricas e a operação. Valide o estado atual do ticket antes de fazer alterações e teste em ambiente controlado antes de usar em produção.

Sobre este artigo

Estas APIs permitem modificar dados reais de tickets — alterar status, prioridade, time e enviar mensagens. Para apenas consultar dados (sem alterar), use Como consultar contatos, tickets e mensagens em tempo real via API.

Autenticação

Todos os endpoints exigem:

Header	Valor
`content-type`	`application/json`
`api_access_token`	Token de administrador ou supervisor

1. Alterar status do ticket (resolver, reabrir, etc.)

Endpoint

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

Body

{
  "status": "resolved"
}

Valores aceitos

Valor	Descrição
`open`	Reabrir ticket
`resolved`	Resolver ticket
`pending`	Marcar como pendente

Exemplo

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"}'

Retorna o objeto da conversa atualizada com status 200 OK.

O endpoint PUT /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} não altera o status — ele só aceita o campo priority. Para alterar status, use sempre o toggle_status acima.

2. Alterar prioridade do ticket

Endpoint

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

Body

{
  "priority": "high"
}

Valores aceitos

Valor	Descrição
`nil` / `null`	Sem prioridade
`low`	Baixa
`medium`	Média
`high`	Alta
`urgent`	Urgente

Exemplo

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"}'

Este endpoint (PUT .../conversations/{ID}) aceita apenas o campo priority. Campos como status, team_id ou outros são silenciosamente ignorados.

3. Alterar status, prioridade e time (Client API)

Para alterar status, prioridade e/ou time em uma única chamada, use a Client API:

Endpoint

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

Este endpoint usa o display_id (ID visível no Cloud Chat), não o conversation_id interno.

Body

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

Campos aceitos

Campo	Descrição
`status`	Status do ticket (`open`, `resolved`, `pending`)
`priority`	Prioridade (`low`, `medium`, `high`, `urgent`)
`team_id`	ID do time para reatribuição

Todos os campos são opcionais — envie apenas o que deseja alterar.

Exemplo

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. Criar mensagem em um 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"
}

Campos

Campo	Obrigatório	Descrição
`content`	Sim	Conteúdo da mensagem
`message_type`	Sim	`incoming` (mensagem do cliente) ou `outgoing` (mensagem do agente/sistema)
`private`	Não	`true` para nota interna (não visível ao cliente)

Exemplo

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. Gerenciar labels (etiquetas) de um ticket

O endpoint PUT /conversations/{ID} não aceita o campo labels. Se você enviar labels no body do PUT, a API retorna 200 mas ignora silenciosamente o campo. Para gerenciar labels, use o endpoint dedicado abaixo.

Endpoint

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

Body

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

Campos

Campo	Tipo	Obrigatório	Descrição
`labels`	array de strings	Sim	Lista de labels a aplicar
`append`	boolean	Não	`true` adiciona às labels existentes. `false` ou omitido substitui todas

Exemplo

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}'

Campos que não podem ser alterados via PUT/PATCH

Alguns campos parecem editáveis mas são ignorados silenciosamente pela API (retorna 200 sem erro):

Campo	Situação	O que fazer
`mail_subject`	Atributo dentro de `additional_attributes`. Só pode ser definido na criação do ticket. Tentativas de atualização via PUT são ignoradas	Não há workaround via API. Se o assunto do e-mail precisa ser diferente, crie um novo ticket
`labels`	Ignorado no PUT/PATCH do ticket	Use o endpoint dedicado `POST .../conversations/{ID}/labels` (seção 5)

Resumo: qual endpoint usar para cada ação

Ação desejada	Endpoint	Método
Alterar status (resolver, reabrir)	`.../conversations/{ID}/toggle_status`	`POST`
Alterar prioridade	`.../conversations/{ID}`	`PUT`
Alterar status + prioridade + time	`/api/client/.../conversations/{DISPLAY_ID}`	`PATCH`
Criar mensagem no ticket	`.../conversations/{ID}/messages`	`POST`
Gerenciar labels	`.../conversations/{ID}/labels`	`POST`

Fluxo seguro recomendado

Consulte o estado atual do ticket antes de alterar — ver Como consultar contatos, tickets e mensagens em tempo real via API
Valide se a ação é necessária (ex: não resolver um ticket já resolvido)
Execute a alteração usando o endpoint correto da tabela acima
Confirme o resultado verificando a resposta da API

Onde encontrar os parâmetros

CLOUDCHAT_DOMAIN — domínio visível na URL do navegador
ACCOUNT_ID — em Configurações da conta
CONVERSATION_ID — ID interno da conversa (retornado nas APIs de consulta)
DISPLAY_ID — ID visível na interface do Cloud Chat (usado apenas na Client API)
API_TOKEN — em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Observações

Para criar tickets novos via API: Como criar tickets via API no Cloud Chat
Para atualizar atributos customizados em conversas: Como atualizar atributos customizados em conversas via API
Para consulta sem alterar dados: Como consultar contatos, tickets e mensagens em tempo real via API
Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API