APIs de consulta em tempo real: contatos, tickets e mensagens

Neste artigo, você encontra os endpoints para leitura em tempo real de dados do Cloud Chat: contatos, tickets e mensagens. Nenhum desses endpoints altera dados.

Sobre o namespace /api/client/

Os endpoints desta página usam /api/client/accounts/... em vez do /api/v1/accounts/... usado em outras APIs. Ambos usam o mesmo api_access_token para autenticação.

O namespace /api/client/ oferece endpoints simplificados de leitura — são mais diretos para consultas pontuais. Para operações de escrita (criar, atualizar, deletar), use os endpoints do namespace /api/v1/.

As APIs de Consulta em Tempo Real permitem ler dados atuais do Cloud Chat, 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 Cloud Chat 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: Cloud Chat.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 Cloud Chat.

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

🔍 1b. Buscar contatos por texto livre (Search)

Quando usar

Use quando precisar buscar um contato por qualquer campo textual — nome, e-mail, telefone, identificador ou nome da empresa — sem saber exatamente qual campo contém a informação.

Diferente do endpoint de busca por e-mail/telefone (seção 1), este endpoint faz uma busca ILIKE (case-insensitive, parcial) em múltiplos campos simultaneamente.

Endpoint

GET /api/v1/accounts/{account_id}/contacts/search?q={termo}

Parâmetros

Campos pesquisados

O endpoint busca simultaneamente em:

• name — nome do contato
• email — e-mail do contato
• identifier — identificador externo
• phone_number — telefone (busca com e sem prefixo +)
• company_name — nome da empresa

Exemplo

GET /api/v1/accounts/1/contacts/search?q=maria&page=1

Retorna todos os contatos cujo nome, e-mail, telefone, identifier ou empresa contenham "maria".

Diferença entre os dois endpoints de busca

📋 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

• Links dos anexos nas mensagens (se houverem)

🧠 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.