APIs de Atualização e Ação em Tickets

As APIs de Atualização e Ação em Tickets permitem modificar dados reais no CloudChat.

Elas são usadas para sincronizar ações de sistemas externos com o CloudChat — por exemplo, resolver um ticket automaticamente, mudar prioridade ou inserir mensagens via integração.

⚠️ Essas APIs escrevem em produção.
Use com cuidado.

🧭 Antes de começar (obrigatório)

Se você ainda não tem clareza sobre qual tipo de API usar, comece pela:

👉 🧭 Guia Mestre — Como acessar e operar dados do CloudChat via API

Este documento explica:

quando usar extração
quando usar consulta
quando usar ação

Esta FAQ cobre apenas APIs de escrita (PUT / POST).

🎯 Para que essas APIs servem?

Use essas APIs quando você precisa:

Resolver ou reabrir tickets automaticamente
Atualizar prioridade ou time responsável
Criar mensagens dentro de um ticket
Sincronizar eventos de outro sistema com o CloudChat

Exemplos de uso legítimo:

Um sistema externo resolve o chamado → o ticket é resolvido no CloudChat
Um SLA estoura → prioridade do ticket é alterada
Um formulário externo gera uma resposta → mensagem é criada no ticket

❌ Para que essas APIs NÃO servem?

Não use essas APIs para:

Ler dados (use APIs de Consulta)
Gerar relatórios (use Data Extract API)
Testes exploratórios sem ambiente controlado
Automatizações sem validação de estado

🚦 Nível de risco (leia com atenção)

Essas APIs têm risco alto, porque:

Alteram tickets reais
Impactam SLAs, métricas e operação
Podem acionar fluxos internos (notificações, automações, etc.)

Boas práticas obrigatórias:

Use apenas quando necessário
Valide estado antes de escrever
Evite múltiplas escritas concorrentes
Teste exaustivamente antes de produção

🔑 Autenticação e domínio

Todos os endpoints exigem:

{CLOUDCHAT_DOMAIN} → domínio real da conta
{ACCOUNT_ID} → ID da conta
api_access_token → token de administrador ou supervisor

⚠️ Nunca utilize localhost em produção.

✏️ 1. Atualizar dados de um ticket

Quando usar

Use este endpoint para alterar propriedades do ticket, como:

status
prioridade
time responsável

Endpoint

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

Exemplo de body

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

O que acontece

O ticket é atualizado imediatamente
Métricas e SLAs são recalculados
A mudança fica registrada no histórico

✉️ 2. Criar mensagem em um ticket (experimental)

⚠️ Disponível apenas para contas com flag ativa

Quando usar

Use este endpoint quando um sistema externo precisa inserir uma mensagem diretamente no ticket.

Exemplos:

Resposta automática após formulário
Integração com outro canal
Mensagem de follow-up programada

Endpoint

POST https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/message

Exemplo de body

{
  "content": "Olá! Entramos em contato a partir da sua solicitação externa.",
  "message_type": "outgoing"
}

Tipos de mensagem

incoming → mensagem vinda do cliente
outgoing → mensagem enviada pelo sistema ou agente

⚠️ Criar mensagens pode:

disparar notificações
impactar métricas de resposta
alterar percepção do cliente

🧠 Fluxo seguro de uso (recomendado)

Sempre que possível, siga esta ordem:

Consultar estado atual do ticket
→ APIs de Consulta em Tempo Real
Validar se a ação é necessária
Executar a atualização ou ação
Evitar reescritas desnecessárias

Nunca “escreva no escuro”.

❌ Erros comuns (e perigosos)

Resolver ticket sem checar status atual
Criar mensagens duplicadas
Rodar PUT/POST em loops automáticos
Usar essas APIs como substituto de leitura
Não entender impacto em SLA e métricas

🔒 Governança e responsabilidade

Recomendações fortes:

Restrinja o token de API
Monitore logs de uso
Documente cada integração que escreve no CloudChat
Trate essas APIs como operações críticas

📌 Próximos passos

Agora você pode acessar as outras APIs do CloudChat:

Sempre comece pelo Guia Mestre e avance para a FAQ correta.