Como consultar contatos, tickets e mensagens em tempo real via API

Quando usar

• Você quer ler dados atuais do Cloud Chat sem alterar nada (consultar contato, ver tickets de um cliente, ler mensagens de uma conversa)

• Você está integrando o Cloud Chat a outro sistema (CRM, portal interno) que precisa exibir dados ao vivo

• Você quer evitar duplicação de contatos antes de criar um ticket

Pré-requisitos

• API Key de administrador ou supervisor — ver Como encontrar sua API Key no Cloud Chat

• CLOUDCHAT_DOMAIN e ACCOUNT_ID

Sobre este artigo

As APIs de Consulta em Tempo Real permitem ler dados atuais do Cloud Chat, diretamente da base de produção, sem alterar nada. 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?"

Sobre o namespace /api/client/

Para que essas APIs servem

Use quando você precisa:

• Ler dados agora

• Integrar dados do Cloud Chat a outro sistema

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

• Tomar decisões baseadas no estado atual do atendimento

Para que não servem

Autenticação

Todos os endpoints exigem:

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

• {ACCOUNT_ID} — ID da conta

• api_access_token — para os endpoints /api/client/ (seções 1, 2 e 3), o token deve ser de administrador — tokens de supervisor ou agente recebem 403 Forbidden. A busca por texto livre (seção 1b, namespace /api/v1/) aceita token de qualquer perfil de agente

1. Buscar contato por e-mail ou telefone

Quando usar

• Antes de criar um ticket (descobrir se o contato já existe)

• 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

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

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

O que 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

Para buscar um contato por qualquer campo textual (nome, e-mail, telefone, identificador, empresa) sem saber exatamente qual contém a informação.

Diferente do endpoint anterior, este faz 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

• name — nome do contato (sempre pesquisado)

• email — e-mail (a partir de 3 caracteres com dígito)

• identifier — identificador externo (a partir de 3 caracteres com dígito)

• phone_number — telefone, com e sem prefixo + (a partir de 3 caracteres com dígito)

• company_name — nome da empresa (a partir de 3 caracteres com dígito)

Resposta

• payload[] — array de contatos encontrados

• meta — contém apenas a página atual

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.

Limite de uso (rate limit)

Diferença entre os dois endpoints de busca

2. Listar tickets de um contato

Quando usar

Já tem o CONTACT_ID e quer listar os tickets desse cliente:

• 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 retorna

• IDs dos tickets

• Status (open, resolved, etc.)

• Prioridade

• Inbox

• Datas de criação

• Se foi iniciado por campanha

3. Listar mensagens de um ticket

Quando usar

Para recuperar o histórico de mensagens de um ticket:

• Auditoria em tempo real

• Exibir 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 retorna

• Conteúdo da mensagem

• Tipo (incoming / outgoing)

• Pública ou privada

• Data de criação

• Status da mensagem

• Links dos anexos (se existirem)

Como essas APIs se conectam (fluxo típico)

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

Nível de risco

Risco médio — não alteram dados, mas consultam a base de produção em tempo real.

Erros comuns

Observações

• Para alterar status, prioridade ou time: Como atualizar e agir em tickets via API

• Para relatórios e BI (extração histórica): Como extrair dados em lote via API

• Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API