Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Quando usar

• Você está prestes a usar uma API do Cloud Chat e quer escolher a categoria certa antes de copiar endpoints
• Você não sabe a diferença entre extração histórica, consulta em tempo real e ação em produção
• Você quer evitar usar a API errada e gerar efeitos colaterais inesperados

Sobre este guia

Este guia existe para responder uma única pergunta:

Qual API do Cloud Chat eu devo usar para o que eu quero fazer?

Antes de copiar qualquer endpoint ou escrever código, leia esta página. Ela evita confusão, uso incorreto de APIs e impactos não desejados em produção.

Existem 3 categorias de APIs no Cloud Chat

As APIs do Cloud Chat não são todas iguais. Elas se dividem em três categorias, cada uma com objetivo claro.

Extração de dados

Para análise histórica e relatórios.

• Exportação em lote (batch)

• Uso típico: BI, auditoria, dashboards

• Não alteram dados

• Ideais para jobs agendados

Consulta em tempo real

Para ler dados atuais do sistema.

• Buscar contatos

• Listar tickets

• Ler mensagens

• Não alteram dados

• Usadas em integrações e automações em tempo real

Atualização e ação

• Resolver tickets

• Alterar status, prioridade ou time

• Criar mensagens em tickets

• Podem impactar operação, SLA e métricas

• Algumas rotas são experimentais ou exigem flag ativa

Quando usar APIs de Extração de Dados

Use APIs de extração quando você quer:

• Criar relatórios

• Alimentar ferramentas de BI

• Fazer auditorias

• Analisar grandes períodos de tempo

• Exportar muitos tickets de uma vez

Essas APIs:

• Funcionam em lote

• Têm limite de intervalo por requisição

• Não devem ser usadas para lógica de aplicação em tempo real

Documentação específica: Como extrair dados em lote via API (Data Extract API)

Quando usar APIs de Consulta em Tempo Real

Use APIs de consulta quando você precisa responder perguntas agora, como:

• "Esse contato já existe?"

• "Quais tickets esse cliente tem?"

• "Qual é o status atual desse ticket?"

• "Quais mensagens foram trocadas nessa conversa?"

Essas APIs:

• São somente leitura (GET)

• Operam diretamente na base de produção

• Não substituem a API de extração

Documentação específica: Como consultar contatos, tickets e mensagens em tempo real via API

Quando usar APIs de Atualização e Ação

Use quando você quer:

• Resolver um ticket via integração

• Atualizar prioridade ou time responsável

• Criar mensagens automaticamente

• Sincronizar ações de outro sistema com o Cloud Chat

Essas APIs:

• Executam ações em produção

• Podem afetar operação e métricas

• Devem ser usadas com cuidado e validação

Documentação específica: Como atualizar e agir em tickets via API

Regra prática para escolher a API certa

Pergunte sempre:

• Quero analisar dados históricos? → Use Data Extract API

• Quero apenas ler dados atuais? → Use APIs de Consulta em Tempo Real

• Quero mudar algo no sistema? → Use APIs de Atualização e Ação

Níveis de cuidado

Quanto mais você se aproxima de ações de escrita, mais atenção e testes são necessários.

Erros comuns que este guia ajuda a evitar

Observações

Próximos passos — escolha a documentação certa para o seu caso:

• Data Extract API — Extração de dados em lote

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

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

Outras APIs para ações específicas:

• Como criar tickets via API

• Como importar contatos em massa via API

• Como importar histórico de tickets via API

• Como encontrar sua API Key no Cloud Chat

Este guia deve sempre ser lido antes das FAQs técnicas acima.