APIs de atualização e ação em tickets

Neste artigo, você encontra os endpoints para modificar dados de tickets no Cloud Chat: alterar status, prioridade, time responsável e enviar mensagens via API.

Estas APIs permitem modificar dados reais de tickets no Cloud Chat — como alterar status, prioridade, time, e enviar mensagens.

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.

Autenticação

Todos os endpoints abaixo exigem:

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

1. Alterar Status do Ticket (resolver, reabrir, etc.)

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

Body

{
  "status": "resolved"
}

Valores aceitos para `status`

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

Exemplo (curl)

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

Resposta

Retorna o objeto da conversa atualizada com status 200 OK.

Atenção: 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

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

Body

{
  "priority": "high"
}

Valores aceitos para `priority`

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

Exemplo (curl)

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

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

3. Alterar Status, Prioridade e Time (via Client API)

Se você precisa alterar status, prioridade e/ou time em uma única chamada, use a Client API:

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

Atenção: 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)

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

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)

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

⚠️ Atenção: 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	Se `true`, adiciona às labels existentes. Se `false` ou omitido, substitui todas as labels

Exemplo (curl)

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 acima).

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 (veja APIs de Consulta em Tempo Real)
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 de configuração

CLOUDCHAT_DOMAIN: O domínio visível na URL do navegador ao acessar o Cloud Chat
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

APIs de atualização e ação em tickets

Autenticação

1. Alterar Status do Ticket (resolver, reabrir, etc.)

Body

Valores aceitos para status

Exemplo (curl)

Resposta

2. Alterar Prioridade do Ticket

Body

Valores aceitos para priority

Exemplo (curl)

3. Alterar Status, Prioridade e Time (via Client API)

Body

Campos aceitos

Exemplo (curl)

4. Criar Mensagem em um Ticket

Body

Campos

Exemplo (curl)

5. Gerenciar Labels (Etiquetas) de um Ticket

Endpoint

Body

Campos

Exemplo (curl)

⚠️ Campos que NÃO podem ser alterados via PUT/PATCH

Resumo: qual endpoint usar para cada ação

Fluxo seguro recomendado

Onde encontrar os parâmetros de configuração

Valores aceitos para `status`

Valores aceitos para `priority`