## 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](/hc/ajuda/articles/api-developers-eventos-por-modulo-pt-br).

## 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

- [SDK, API REST e MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-pt-br)
- [Visão geral de API & Desenvolvedores](/hc/ajuda/articles/api-developers-overview-pt-br)
- [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-pt-br)
- [Referência de API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-pt-br)