APIs de Consulta em Tempo Real (Contacts, Tickets e Messages)

As APIs de Consulta em Tempo Real permitem ler dados atuais do CloudChat, diretamente da base de produção, sem alterar nada no sistema.

Elas são ideais para integrações, automações e telas internas que precisam responder perguntas como:

• “Esse contato já existe?”

• “Quais tickets esse cliente tem?”

• “Qual é o status atual desse ticket?”

• “Quais mensagens foram trocadas nessa conversa?”

🧭 Antes de começar (leia isso)

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

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

Ele explica a diferença entre:

• APIs de Extração de Dados (histórico / batch)

• APIs de Consulta em Tempo Real (leitura)

• APIs de Atualização e Ação (escrita)

Esta FAQ cobre apenas leitura em tempo real.

🎯 Para que essas APIs servem?

Use as APIs de Consulta em Tempo Real quando você precisa:

• Ler dados agora

• Integrar os dados do Cloud Chat a outro sistema

• Exibir informações em uma aplicação

• Tomar decisões baseadas no estado atual do atendimento

Essas APIs não são para relatórios históricos nem para exportação em massa.

❌ Para que essas APIs NÃO servem?

Não use essas APIs para:

• Gerar relatórios

• Exportar grandes volumes de dados

• Analisar períodos longos de tempo

• Criar ou atualizar tickets

• Inserir mensagens

👉 Para isso, veja:

• 📦 API de Extração de Dados (Data Extract API)

• ✏️ APIs de Atualização e Ação em Tickets

🔑 Autenticação e domínio

Todos os endpoints abaixo exigem:

• {CLOUDCHAT_DOMAIN} → domínio da sua conta (ex: cloudchat.cloudhumans.com)

• {ACCOUNT_ID} → ID da conta

• api_access_token → token de administrador ou supervisor

🔎 1. Buscar contato por e-mail ou telefone

Quando usar

Use este endpoint quando você quer descobrir se um contato já existe no CloudChat.

Exemplos:

• Antes de criar um ticket

• Para associar dados externos a um contato

• Para evitar duplicação

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts?email=EMAIL&phone_number=PHONE

Regras importantes

• Pelo menos um dos parâmetros (email ou phone_number) é obrigatório

• Se ambos forem enviados, a API tenta fazer o match mais preciso possível

O que ele retorna

• ID do contato

• Nome

• E-mail

• Telefone

• Campos personalizados

• Datas de criação e última atividade

📋 2. Listar tickets de um contato

Quando usar

Use este endpoint quando você já tem o CONTACT_ID e quer listar os tickets desse cliente.

Exemplos:

• Mostrar histórico de atendimentos

• Ver tickets abertos ou resolvidos

• Integrar com CRM ou portal interno

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/conversations?page=1&limit=10

Parâmetros

• page → obrigatório

• limit → opcional (padrão: 10)

O que ele retorna

• IDs dos tickets

• Status (open, resolved, etc.)

• Prioridade

• Inbox

• Datas de criação

• Se o ticket foi iniciado por campanha

💬 3. Listar mensagens de um ticket

Quando usar

Use este endpoint para recuperar o histórico de mensagens de um ticket específico.

Exemplos:

• Auditoria em tempo real

• Exibição de conversa em outra interface

• Debug de integrações

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/messages?page=1&limit=10

O que ele retorna

• Conteúdo da mensagem

• Tipo (incoming / outgoing)

• Se é privada ou pública

• Data de criação

• Status da mensagem

🧠 Como essas APIs se conectam (fluxo típico)

Um fluxo comum de uso é:

1. Buscar contato por e-mail ou telefone

2. Obter o CONTACT_ID

3. Listar os tickets desse contato

4. Escolher um ticket

5. Listar as mensagens do ticket

Tudo isso sem alterar nenhum dado.

🚦 Nível de risco dessas APIs

Essas APIs são consideradas de risco médio, porque:

• Não alteram dados

• Mas consultam a base de produção em tempo real

Boas práticas:

• Evite loops agressivos

• Use cache quando possível

• Não use para exportação em massa

❌ Erros comuns

• Usar essas APIs para relatórios históricos

• Esquecer o parâmetro page

• Confundir CONTACT_ID com CONVERSATION_ID

• Tentar criar ou atualizar dados com GET

📌 Próximos passos

Agora você pode seguir para:

• ✏️ APIs de Atualização e Ação em Tickets
  (quando precisar alterar status, prioridade ou criar mensagens)

• 📦 API de Extração de Dados (Data Extract API)
  (para relatórios, BI e auditoria)

E lembre-se:
👉 Sempre consulte o Guia Mestre antes de usar uma nova API.