Central de Ajuda Conversa Labs
pt_BR
Idioma
pt_BR Portuguese (Brazil) en English es Spanish

API REST, tokens e webhooks

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Conversa Labs

Conversa Labs

Última atualização em Aug 23, 2026

Visão geral

A API REST permite ler e gravar dados da plataforma (contatos, conversas, mensagens e mais). A autenticação é por token de acesso, e os webhooks entregam eventos ao seu sistema em tempo real.

Pré-requisitos

  • Token de acesso válido.
  • Um endpoint HTTPS para receber webhooks.

Passo a passo

  1. Gere um token de acesso nas configurações.
  2. Inclua o token no cabeçalho de autenticação das chamadas à API.
  3. Faça requisições aos recursos da API (ex.: listar contatos, criar conversa).
  4. Configure um webhook informando a URL e os eventos desejados.
  5. Valide a assinatura/segredo do webhook antes de processar o payload.

Configurações & opções

  • Escopo do token: limite o acesso ao necessário.
  • Eventos do webhook: assine apenas os eventos que você usa.
  • Segredo de assinatura: ele aparece uma única vez, logo após a criação do webhook. Copie e guarde com segurança; listagem e edição apenas confirmam que há um segredo configurado e nunca o revelam. Se ele for perdido, crie um webhook substituto e depois remova o destino antigo.
  • Entrega durável: cada envio de webhook de conta é registrado antes de entrar na fila. Erros de rede e respostas 5xx usam retentativas com backoff e permanecem visíveis no histórico.
  • Histórico e reenvio: em Configurações → Integrações → Webhooks, abra o histórico do destino para buscar, filtrar e ordenar tentativas. Um administrador pode reenviar uma ou várias linhas; em lote, a tela separa os IDs processados dos que falharam.
  • Payload de Commerce: o padrão envia somente os identificadores canônicos. Ative Incluir dados comerciais no destino apenas quando o sistema receptor precisar de comprador, produto/variação e itens normalizados. O opt-in não inclui credenciais nem o payload bruto do gateway.
  • Reentrega no receptor: use o cabeçalho X-Chatwoot-Delivery como chave de idempotência; um reenvio manual reutiliza o mesmo identificador.

Catálogo de eventos (grupos de módulos)

Todos os eventos abaixo são assinaturas de nível de conta (configuradas por conta, na tela de Webhooks). Para um módulo entregar seus eventos, o recurso do módulo precisa estar habilitado na conta — a assinatura é aceita mesmo com o recurso desligado, mas nada é entregue até ativá-lo.

  • Conversas, mensagens, contatos, caixa de entrada e digitação — ciclo de vida do atendimento.
  • CRM (negócios) — criação, etapa, ganho/perdido, prioridade, valor, saúde, checklist, SLA e datas de fechamento.
  • Catálogo e Commerce — produtos, variações/estoque e ciclo de pagamento do Commerce.
  • Pedidos e receita — registro de pedido, status, pago, reembolsado, receita e afiliados.
  • Tarefas, Agenda e agendamentos, Pagamentos e Follow-ups — ciclos de vida de cada módulo.
  • Contratos e assinatura eletrônica, Gestão de Vendas e Engajamento/Lead Score.
  • Account Brain — risco, insights, execução de departamento e melhorias propostas.
  • Distribuição (Grupos de Lançamento) — inscrição, convite, entrada de membros e conclusão de unidades.
  • Growth Social e Ads — comentários, leads de anúncio, status de campanha e janela do Clique-para-WhatsApp.
  • WhatsApp Hub — transmissões, eventos de participantes e boas-vindas/despedidas de grupo (Cloud e WazMeow).
  • Chamadas e respostas de Flow do WhatsApp — ciclo de vida das chamadas e respostas de WhatsApp Flows.
  • Gestão de Equipe — mudança de status, pausas e turnos dos agentes.
  • FlowBuilder — ciclo de vida das sessões de fluxo.
  • Roteamento Inteligente — atribuição de agente.

Os campos reais de cada payload estão em Eventos por módulo.

Casos de uso

  • Espelhar conversas em um data warehouse.
  • Notificar um sistema externo quando uma conversa é criada ou resolvida.

Dicas, limites e boas práticas

  • Sempre verifique a assinatura do webhook antes de agir.
  • Garanta idempotência com X-Chatwoot-Delivery, inclusive em retentativas e reenvios manuais.
  • Respeite limites de taxa e use backoff em erros 429/5xx.

Solução de problemas

  • 401/403: token inválido ou sem permissão.
  • Webhook duplicado: confirme se o receptor deduplica X-Chatwoot-Delivery.
  • Entrega falhou: abra o histórico do destino, confira status HTTP/erro e a próxima tentativa. Após corrigir o receptor, selecione a linha e confirme o reenvio.

Veja também