API do Chakra Chat: guia completo para desenvolvedores de automação do WhatsApp

Em resumo: a API do Chakra Chat se baseia na WhatsApp Cloud API e oferece o que o acesso direto à Meta não disponibiliza por padrão: chaves de API com escopo por função, um formato de webhook mais simples além do repasse completo da Meta, gerenciamento integrado de leads e campanhas, endpoints de chamadas e uma camada mais ampla de Plataforma/CRM (processos, tarefas, usuários) para criar fluxos de trabalho reais — não apenas enviar mensagens. Este guia aborda a autenticação (chaves de API, funções, tokens Bearer), as seis áreas de recursos em que a API está organizada, os limites de chamadas (200 chamadas/minuto), o funcionamento dos webhooks recebidos e da validação HMAC, quando usar o SDK oficial TS/JS em vez de chamadas HTTP diretas e os padrões de integração — sincronização com CRM, acionadores de automação por meio de ferramentas como n8n, plataformas de e-commerce como Shopify e envios em massa — que atendem à maioria dos casos de uso reais. Este é o guia para ler antes de abrir a documentação da API no nível dos endpoints — ele explica o motivo e a estrutura do sistema, não apenas cada chamada individual.

Introdução

Se você está avaliando a API do Chakra Chat, provavelmente já consultou diretamente a documentação da WhatsApp Cloud API e quer saber o que uma camada de BSP realmente acrescenta. Este guia responde a essa pergunta e, em seguida, explica os aspectos práticos — autenticação, arquitetura, limites de chamadas, webhooks, SDK e os padrões de integração que a maioria dos desenvolvedores acaba criando. Para detalhes no nível dos endpoints (esquemas de solicitação/resposta, parâmetros), consulte a documentação da API do Chakra junto com este guia.

O que a API do Chakra oferece em comparação com o acesso direto à WhatsApp Cloud API

A Cloud API da Meta é a camada fundamental — é ela que envia e recebe mensagens do WhatsApp, gerencia modelos e cuida da infraestrutura de números de telefone. Todos os Provedores de Soluções do WhatsApp Business, incluindo o Chakra, são, em última análise, criados sobre ela. Então, por que não integrar diretamente com a Meta?

Para algumas equipes, essa é uma opção razoável. Mas trabalhar diretamente com a Meta significa assumir tudo o que ela não oferece de forma nativa: verificação da empresa e fluxo de integração, ferramentas de aprovação de modelos, uma caixa de entrada fácil de usar para os membros da equipe que não são desenvolvedores e — algo essencial para qualquer operação além de um único fluxo automatizado — a lógica de negócios complementar, como acompanhamento de leads, gerenciamento de campanhas e manutenção de registros no estilo CRM, que não existe na API da Meta.

O que a API do Chakra acrescenta ao acesso direto à Cloud API:

• Formato de repasse e formato de webhook mais simples. Você pode receber diretamente eventos no formato bruto da Meta ou usar um formato de eventos normalizado do Chakra, mais fácil de trabalhar — a escolha é sua, conforme o caso de uso.
• Chaves de API com escopo por função em vez de uma única credencial para toda a conta, para que diferentes integrações (uma sincronização com Shopify, uma automação no n8n, um painel interno) tenham apenas o acesso de que realmente precisam.
• Uma camada de Leads e Campanhas — endpoints específicos para criar e atualizar leads e gerenciar campanhas de leads, em vez de você ter que criar esse modelo de dados sobre eventos de mensagens brutos.
• Uma camada de Plataforma/CRM — Processos, Tarefas, Usuários e Tarefas em Segundo Plano, com elementos genéricos para fluxos de trabalho e manutenção de registros que complementam os endpoints específicos do WhatsApp. Eles são úteis quando a integração com o WhatsApp faz parte de um sistema operacional mais amplo.
• Endpoints da API de chamadas para o recurso de chamadas de voz do WhatsApp — configurações, permissões e gerenciamento de chamadas — como uma área de recursos compatível de forma nativa, e não algo integrado separadamente.
• Uma caixa de entrada compartilhada e ferramentas para quem não é desenvolvedor na mesma conta, para que a API não seja a única forma de acessar o sistema — as equipes de suporte e marketing trabalham na mesma plataforma com a qual suas integrações se conectam.

Quando uma integração direta com a Meta ainda pode fazer sentido: se você está criando uma infraestrutura em escala massiva com uma equipe de plataforma dedicada ou precisa de funcionalidades da Cloud API assim que a Meta as disponibiliza, antes que qualquer camada de BSP as ofereça. Para a maioria das equipes de produto e crescimento — qualquer pessoa que esteja criando automações, sincronização com CRM ou fluxos voltados para clientes sem querer assumir toda a infraestrutura de mensagens — uma API de BSP como a do Chakra é o caminho mais rápido e fácil de manter.

Autenticação: chaves de API, funções e tokens Bearer

Todas as chamadas à API do Chakra são autenticadas com uma chave de API, e a configuração foi estruturada intencionalmente para priorizar o acesso com os menores privilégios possíveis, em vez de usar uma única credencial com acesso irrestrito.

Como criar uma chave de API:

1. Acesse a seção Chaves de API na sua conta do Chakra Chat.
2. Dê um nome significativo — como provavelmente você terá várias chaves com o tempo, identificá-las pelo caso de uso ("n8n-support-bot", "shopify-order-sync") facilita muito o gerenciamento no futuro, em comparação com nomes genéricos.
3. Adicione uma descrição opcional para incluir mais contexto.
4. Atribua uma função de acesso. A chave herda exatamente os privilégios da função atribuída — nada além disso.

Como usar a chave: depois de criá-la, abra a visualização de detalhes da chave e localize a seção Tokens de acesso . O token exibido ali deve ser enviado como um token Bearer no cabeçalho Authorization de todas as solicitações à API:

Authorization: Bearer {your_access_token}

A diretriz prática mais importante: sempre limite as chaves aos menores privilégios de que o caso de uso realmente precisa. Alguns hábitos concretos que isso implica:

• Use chaves separadas para cada integração, em vez de uma única chave compartilhada entre todas as automações. Se uma integração específica for comprometida ou apresentar problemas, uma chave com escopo limitado restringe o impacto às permissões daquela integração.
• Tenha cuidado especial com chaves expostas no frontend. Qualquer chave de API usada em código do lado do cliente fica visível para quem inspecionar o tráfego de rede — essas chaves devem ter o mínimo possível de privilégios e, idealmente, nunca devem permitir gravações em operações sensíveis, como mensagens ou dados de leads.
• Revise periodicamente as funções das chaves, especialmente à medida que as integrações evoluem — às vezes, uma chave criada para um caso de uso inicial e específico acaba assumindo responsabilidades mais amplas ao longo do tempo, sem que sua função seja revisada.

Arquitetura da API: as seis áreas de recursos

A API do Chakra está organizada em seis áreas práticas de recursos. Entender essa estrutura desde o início facilita muito encontrar o endpoint certo depois, em vez de pesquisar toda a documentação de referência a cada vez.

1. Mensagens — envio e recebimento de mensagens reais do WhatsApp. Isso abrange mensagens de sessão (texto livre, dentro da janela de 24 horas), upload e recuperação de mídia, gerenciamento de chaves do WhatsApp Flows e gerenciamento de Grupos (criar, listar, gerenciar participantes e solicitações para entrar). Aqui estão disponíveis tanto uma opção de repasse no formato da Meta quanto endpoints nativos de mensagens do Chakra.

2. Modelos — criação, listagem e atualização de modelos de mensagem do WhatsApp, além de endpoints específicos para enviar mensagens de modelo a um número de telefone ou no contexto de um Processo (veja Plataforma abaixo). O envio de modelos e o gerenciamento de modelos são grupos de endpoints deliberadamente separados, pois o ciclo de criação/gerenciamento (sujeito ao processo de aprovação da Meta) é diferente do ato de enviar um modelo já aprovado.

3. Leads — criação e atualização de registros de leads por número de telefone, oferecendo uma forma estruturada de acompanhar clientes em potencial e clientes vinculados a conversas do WhatsApp, sem precisar criar esse modelo de dados do zero sobre dados brutos de conversas.

4. Campanhas — adição ou remoção de números de telefone em campanhas de leads, o recurso básico para sequências estruturadas de mensagens proativas (fluxos de nutrição, segmentos de transmissão), em vez de envios pontuais.

5. Chamadas — a superfície da API de Chamadas do WhatsApp: consulta e configuração das definições de chamadas de um número de telefone, verificação do status de permissão para chamadas (se determinado contato concedeu permissão para chamadas iniciadas pela empresa) e gerenciamento de chamadas ativas.

6. Plataforma/CRM — a camada genérica de fluxo de trabalho: Processos (criar, atualizar, listar, operações em lote, excluir — essencialmente registros estruturados configuráveis), Tarefas, Usuários, Fotos e Tarefas em segundo plano. Essa parte da API não é específica do WhatsApp — é um conjunto leve de recursos básicos de CRM/fluxo de trabalho que complementa os recursos de mensagens. É útil quando você quer manter a integração com o WhatsApp e seus dados operacionais mais amplos no mesmo sistema, em vez de conectá-los entre ferramentas separadas.

Além dessas seis áreas, vale conhecer outras duas áreas de suporte: Chat e mensagens do Chat (listagem de chats e histórico de mensagens de um número de telefone ou conversa — útil para criar visualizações personalizadas da caixa de entrada ou levar contexto para outro sistema) e Acesso de parceiros (criação de tokens de conexão e gerenciamento da configuração de plugins do WhatsApp/WABA — relevante se você estiver criando algo com base no Chakra como parceiro integrado, em vez de uma integração de conta única).

Limites de taxa e o que eles significam na prática

O Chakra impõe um limite de 200 chamadas de API por minuto. Esse é o número que deve orientar o seu planejamento, não apenas algo de que você deve estar ciente.

Na prática, isso significa:

• Operações em lote exigem processamento em lotes, não força bruta. Se você estiver sincronizando uma lista grande de leads ou enviando uma transmissão para milhares de destinatários, organize o trabalho em lotes com intervalos entre eles, em vez de disparar cada solicitação o mais rápido possível, conforme o loop do seu código permitir.
• Implemente o tratamento de novas tentativas com espera progressiva. Qualquer integração que faça chamadas frequentes deve tratar com elegância as respostas de limite de taxa — tente novamente com intervalos progressivos, em vez de interromper toda a operação ou sobrecarregar a API logo após receber uma resposta de limite.
• Arquiteturas orientadas por webhooks naturalmente permanecem abaixo do limite na maioria dos casos de uso, já que respondem a eventos recebidos em vez de fazer consultas periódicas — esse é mais um motivo para priorizar webhooks (abordados a seguir) em vez de padrões de consulta periódica para qualquer operação com muitas leituras, como verificar novas mensagens ou atualizações de status.
• Tarefas de transmissão ou sincronização de alto volume devem ser executadas como tarefas em segundo plano, e não dentro de uma solicitação voltada ao usuário — os endpoints de Tarefas em segundo plano da camada Plataforma existem, em parte, por esse motivo: permitem acompanhar operações em lote de longa duração sem esbarrar em tempo real no limite de 200 por minuto.

Webhooks: eventos recebidos e o que você pode fazer com eles

O WhatsApp — e, por extensão, a API do Chakra — funciona de forma assíncrona. Quando você envia uma mensagem, a API aceita a solicitação e, mais tarde, publica eventos indicando se ela foi enviada, entregue, lida ou se houve falha. As mensagens recebidas dos clientes também são entregues como eventos, em vez de serem algo que você consulta periodicamente. Por isso, os webhooks são a base de qualquer integração em tempo real.

Há dois tipos distintos de webhook, e escolher o certo faz diferença:

Webhook de eventos de repasse — entrega diretamente ao seu endpoint o formato bruto dos eventos da Meta, sem modificações. Isso inclui mensagens recebidas, eventos de status, notificações de atualização de modelos e atualizações no nível da conta. Configure-o na aba "Mais" da página Configuração do WhatsApp, no campo da URL do webhook de repasse. Como o formato corresponde exatamente ao da documentação da Meta, essa é a opção certa se você já conhece as cargas de dados da Cloud API ou precisa acessar tipos de eventos que o formato normalizado não abrange.

Webhook de eventos do Chakra — um formato mais amigável e normalizado para um conjunto selecionado de tipos de evento, configurado na mesma página Configuração do WhatsApp, ativando "Webhooks do Chakra" e selecionando os tipos de evento que você quer receber. Os eventos chegam com duas chaves consistentes: event (um dos valores message, status, message_echoou smb_message_echo) e payload (os dados correspondentes da mensagem ou do status de entrega). Essa é a melhor opção padrão para a maioria das integrações, já que você não precisa analisar toda a estrutura aninhada de eventos da Meta para casos de uso simples, como "me avise quando um cliente responder".

Um exemplo de evento de mensagem de texto recebida (formato de repasse) dá uma ideia da estrutura com que você vai trabalhar:

{  "object": "whatsapp_business_account",  "entry": [{    "id": "83784929738012",    "changes": [{      "value": {        "messaging_product": "whatsapp",        "metadata": { "display_phone_number": "917259775805", "phone_number_id": "694794789348887" },        "contacts": [{ "profile": { "name": "John" }, "wa_id": "919911223344" }],        "messages": [{          "from": "919911223344",          "id": "wamid.xxxx",          "timestamp": "1756322278",          "text": { "body": "Hi, can you please help me out with an issue" },          "type": "text"        }]      },      "field": "messages"    }]  }]}

Proteja seu webhook com validação HMAC. Como os endpoints de webhook precisam ser acessíveis publicamente e não exigem autenticação integrada, é importante verificar se as solicitações recebidas realmente se originaram do Chakra. Veja como:

1. Defina um segredo HMAC em Administração → Equipe → Segredos na sua conta do Chakra. Depois de defini-lo, cada evento de webhook incluirá um cabeçalho X-Chakra-Signature-256 .
2. Do seu lado, calcule um hash HMAC-SHA256 da string bruta do corpo da solicitação (não de um objeto JSON analisado e serializado novamente — muitos frameworks HTTP transformam o corpo, o que invalida a comparação), usando seu segredo como chave.
3. Compare o hash calculado com o valor em X-Chakra-Signature-256 (observação: o valor do cabeçalho não tem o prefixo sha256= , ao contrário do padrão usado por alguns outros provedores). Se os valores corresponderem, a carga de dados é autêntica e não foi adulterada.

💡Se você pular essa etapa, qualquer pessoa que descobrir a URL do seu webhook poderá enviar eventos falsos para ele — considere isso uma etapa obrigatória para qualquer integração em produção, não uma medida de segurança opcional.

O SDK — quando usar e quando fazer chamadas diretas à API

A Chakra publica um SDK oficial de TypeScript/JavaScript, @chakrahq/chakra-chat-sdk, que pode ser usado em ambientes JavaScript tanto no servidor quanto no cliente.

npm i @chakrahq/chakra-chat-sdk

Todas as solicitações feitas pelo SDK são autenticadas com o mesmo token de acesso Bearer usado em chamadas diretas à API. Ele é informado uma única vez na inicialização, em vez de ser adicionado manualmente a cada chamada.

Quando o SDK é a melhor opção:

• Você está desenvolvendo em um ambiente Node.js ou JavaScript/TypeScript e quer estruturas tipadas para solicitações e respostas, em vez de criar chamadas HTTP e analisar JSON bruto por conta própria.
• Você está chamando vários endpoints no mesmo serviço e quer um único cliente inicializado, em vez de repetir a lógica dos cabeçalhos de autenticação em todos os lugares.
• Você quer acelerar o desenvolvimento inicial e não se importa em acompanhar o ritmo de lançamento do SDK para ter acesso a novos endpoints.

Quando faz mais sentido usar chamadas HTTP diretas:

• Você está integrando a partir de um ambiente que não usa JavaScript (Python, Ruby, Go ou uma ferramenta low-code como o nó HTTP Request do n8n) — a API pode ser usada por completo com solicitações HTTP simples. Na verdade, esse é o padrão mais comum para integrações com plataformas de automação, já que ferramentas como o n8n funcionam nativamente com nós HTTP, em vez de importar um pacote npm.
• Você precisa de um endpoint disponível na API direta, mas que ainda não esteja incluído na versão atual do SDK.
• Você está fazendo uma integração simples e pontual, e não vale a pena adicionar uma dependência de SDK completa para usar apenas algumas chamadas.

Na prática, a maioria das equipes acaba usando os dois: o SDK em um serviço central de backend que se comunica regularmente com a Chakra e chamadas HTTP diretas em integrações mais simples, como fluxos de trabalho em plataformas de automação ou funções serverless acionadas por webhooks.

Padrões comuns de integração

Sincronização com CRM. Use os endpoints de Leads (Create a lead, Update Lead By Phone Number) para manter sincronizado o registro de um cliente ou prospect à medida que as conversas no WhatsApp avançam. Combine esses endpoints com os endpoints de Process/Task da camada Platform se quiser acompanhar registros estruturados e o estado dos fluxos de trabalho no mesmo sistema, em vez de fazer chamadas de ida e volta a um CRM externo a cada atualização.

Acionadores de automação via n8n. Um padrão comum: configure o webhook de repasse para apontar para um nó de acionamento de webhook do n8n, filtre os eventos de mensagem, envie o conteúdo da mensagem para um nó AI Agent (ou para qualquer lógica de processamento) e, em seguida, envie a resposta de volta por um nó HTTP Request que chama diretamente o endpoint de mensagens:

POST https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v22.0/{whatsappPhoneNumberId}/messagesAuthorization: Bearer {chakraAccessToken}Content-Type: application/json

Os valores de pluginId e whatsappPhoneNumberId estão disponíveis na página WhatsApp Setup da sua conta Chakra — o ID do plugin fica no menu de três pontos ao lado de Save, e o Meta ID do número de telefone fica no ícone de engrenagem ao lado da lista de números de telefone. Esse padrão — webhook de entrada, processamento e chamada HTTP de saída — também funciona muito bem em outras ferramentas de automação de fluxos de trabalho que oferecem suporte a acionadores de webhook e nós de solicitação HTTP.

Automação do ciclo de vida de pedidos de e-commerce (integração do tipo Shopify). Em vez de criar isso usando webhooks diretamente, plataformas como Shopify geralmente se conectam por meio de uma camada de sincronização no-code que mapeia automaticamente eventos do ciclo de vida do pedido (criado, processado, enviado, entregue) para o envio de mensagens de modelo, além de encaminhar eventos de checkout abandonado para sequências de modelos de recuperação de carrinho. Para plataformas de e-commerce personalizadas ou que não sejam Shopify e não tenham uma integração nativa, é possível implementar o mesmo padrão diretamente na API: um webhook de status do pedido da sua plataforma aciona um manipulador no servidor, que chama o endpoint de envio de modelos com as variáveis corretas preenchidas com os dados do pedido.

Envio em massa via API. Para enviar um modelo de Marketing ou Utility a um segmento de contatos — em vez de enviar uma única resposta de conversa —, o padrão é: montar a lista de destinatários (geralmente pelos endpoints de Campaigns, adicionando números de telefone a uma campanha de leads) e, em seguida, percorrer a lista enviando mensagens ao endpoint de envio de modelos, respeitando o limite de 200 chamadas por minuto com processamento em lotes e intervalos progressivos, conforme explicado acima. Para listas grandes, executar esse processo como uma tarefa em segundo plano, em vez de fazer um loop síncrono, ajuda a lidar com falhas parciais e pausas causadas pelo limite de chamadas.

Próximos passos

Este guia aborda a arquitetura e as justificativas — os detalhes de cada endpoint (corpos exatos das solicitações, esquemas de resposta e a lista completa de operações disponíveis em cada área de recursos) estão na documentação da API da Chakra. Vale salvar alguns documentos nos favoritos antes de começar a desenvolver:

• Chaves de API — como criar e definir o escopo das chaves
• Webhook de eventos recebidos — referência completa de webhooks e validação HMAC
• Limites de chamadas da API
• Chakra Chat SDK
• Como encontrar pluginId e whatsappPhoneNumberId — necessários para a maioria das integrações HTTP diretas

Para acompanhar um passo a passo prático de uma automação específica, os guias de integração de AI Agent com n8n e de integração com Shopify desenvolvem os conceitos abordados aqui — comece por este guia para entender a estrutura do sistema e depois use os outros para seguir uma implementação concreta, passo a passo.