Glossário de API de WhatsApp
41 termos que aparecem em qualquer integração de WhatsApp, definidos de forma direta: o que significam, onde aparecem na API e o que muda na prática de quem implementa.
41 termos que aparecem em qualquer integração de WhatsApp, definidos de forma direta: o que significam, onde aparecem na API e o que muda na prática de quem implementa.
Este glossário cobre o vocabulário completo de uma integração de WhatsApp por API — do básico de HTTP aos termos que só aparecem quando o número já está em produção, como aquecimento, opt-out e bloqueio temporário. Os exemplos usam os endpoints e os eventos reais da API do zapon, então cada definição pode ser conferida na documentação.
Cada termo tem endereço próprio: /glossario/#webhook, /glossario/#jid, /glossario/#opt-in-e-opt-out e assim por diante. Dá para linkar direto de um chamado, de um manual interno ou de um contrato.
Os conceitos que valem para qualquer integração HTTP e aparecem em toda documentação de API de WhatsApp.
API é o conjunto de regras que permite que dois sistemas troquem dados sem intervenção humana. No caso do WhatsApp, é o que permite que o seu software envie e receba mensagens sem que alguém digite no aplicativo. Em vez de uma tela, existe um contrato: você manda uma requisição com os dados combinados, o outro lado executa a ação e devolve uma resposta previsível. Esse contrato é o que torna a integração automatizável, porque o mesmo pedido, feito mil vezes, se comporta igual. Toda a documentação do zapon descreve exatamente esse contrato: quais caminhos existem, o que cada um espera receber e o que devolve.
API REST é o estilo de API que usa HTTP como protocolo e trata cada recurso como um endereço próprio, acessado por métodos como GET e POST. É o formato mais comum da web porque não exige biblioteca: qualquer linguagem que faça uma requisição HTTP consegue consumir. A API do zapon é REST — você chama https://api.zapon.dev com um método, um header de autenticação e um corpo em JSON, e recebe uma resposta em JSON. Não há SDK obrigatório, dependência para instalar nem processo seu para manter rodando. Na prática, a mesma integração é feita em backend próprio, em ferramenta de automação visual ou em um script de linha de comando.
Endpoint é um caminho específico de uma API que executa uma ação, identificado pela combinação de método HTTP e URL. POST /chat/send/text é um endpoint; GET /group/list é outro. Cada endpoint tem os próprios campos obrigatórios e o próprio formato de resposta, e é isso que a referência descreve. Na API do zapon os endpoints são agrupados em três famílias: /chat/* para enviar mensagens e agir sobre elas, /group/* para administrar grupos e /user/* para consultar contatos. Conectar o número não é um endpoint: isso se faz no painel, na tela de Conexões. Saber em qual família procurar resolve a maior parte das dúvidas antes de abrir o suporte.
JSON é o formato de texto que representa dados estruturados em pares de chave e valor, e é o formato que a API do zapon usa no corpo das requisições, nas respostas e nos eventos entregues por webhook. Um envio de texto é um objeto JSON com os campos Phone e Body; uma mensagem recebida é um objeto JSON com o conteúdo completo. Você declara o formato na requisição pelo header Content-Type: application/json. Toda linguagem moderna serializa e desserializa JSON de forma nativa, então na prática você monta um dicionário ou um objeto e a biblioteca HTTP cuida do resto.
POST é o método HTTP usado para enviar dados ao servidor com o objetivo de criar algo ou executar uma ação. Na API do zapon, praticamente tudo que produz efeito é POST: enviar mensagem, reagir, marcar como lida, criar grupo, atualizar participantes. Consultas que apenas leem informação usam GET, como a lista de grupos e o status da sessão. A distinção não é decorativa: POST carrega corpo em JSON e não deve ser repetido às cegas, porque cada chamada bem-sucedida gera um efeito novo — uma segunda tentativa de envio manda uma segunda mensagem ao contato, não a mesma.
Payload é o conteúdo de dados que viaja no corpo de uma requisição ou de um evento, separado dos cabeçalhos que descrevem o transporte. No envio, o payload é o JSON com os campos da mensagem. No recebimento, é o JSON que o zapon entrega no seu webhook, com a mensagem completa: remetente, tipo, conteúdo, identificador e horário. O payload de evento vem inteiro, então você não precisa de uma segunda chamada para descobrir o que o contato escreveu. Ao depurar uma integração, registrar o payload cru antes de qualquer tratamento é o atalho mais rápido para achar o campo que está faltando.
Header de autenticação é o cabeçalho HTTP que identifica quem está chamando a API. Na API do zapon ele se chama token e recebe o token da conexão, sem prefixo: não é Authorization e não é Bearer. Você o envia junto do Content-Type: application/json em toda requisição. Trocar o valor desse header é como o seu código escolhe de qual número a mensagem sai, já que cada conexão tem o seu. Erro no header é a causa mais comum de resposta 401, e vale conferir se o token é o da conexão certa antes de investigar qualquer outra coisa. O detalhe está em Autenticação.
Token de API é a chave secreta que autentica as chamadas de uma conexão. No zapon o token pertence a um número, não à conta: cinco números conectados significam cinco tokens, e cada um só alcança o próprio número. Esse isolamento é o que permite atender vários clientes na mesma conta sem que o tráfego de um encoste no do outro. Trate o token como senha — guarde no servidor ou em variável de ambiente, nunca em código de front-end, repositório público ou coleção compartilhada —, porque quem tem o token envia mensagens em nome do número. Se ele vazar, gere um novo pelo painel.
Como interpretar o que a API devolve e como chamar de novo sem duplicar mensagem nem acelerar o risco.
Status HTTP é o código numérico que a API devolve para classificar o resultado da requisição, antes mesmo de você olhar o corpo da resposta. Vale tratar cada faixa de forma diferente, porque a ação necessária muda: 200 é requisição aceita, e é quando você guarda o identificador da mensagem; 400 é corpo inválido, em geral campo obrigatório ausente ou número em formato errado; 401 é token ausente ou inválido; 404 é caminho inexistente; 500 é erro ao processar e com frequência indica conexão fora do ar. Erro de configuração não se resolve repetindo a chamada. A tabela completa está em Erros e respostas.
Timeout é o tempo máximo que o seu código espera pela resposta antes de desistir da requisição; retry é a nova tentativa feita depois de uma falha. Os dois andam juntos na configuração de qualquer cliente HTTP. Defina um timeout explícito: sem ele, uma chamada travada segura a sua fila por tempo indeterminado. E limite o retry ao que faz sentido — repetir um 500 ou um erro de rede é razoável, com espera crescente entre as tentativas, enquanto repetir um 400 ou um 401 apenas multiplica o mesmo erro. Cuidado com o retry cego em envio de mensagem: se a primeira chamada chegou a ser processada, a segunda gera uma mensagem duplicada para o contato.
Idempotência é a propriedade de uma operação que, repetida com os mesmos dados, produz o mesmo resultado, sem efeito adicional. Envio de mensagem não é naturalmente idempotente: duas chamadas iguais entregam duas mensagens ao contato. Por isso a responsabilidade de não duplicar fica do seu lado. O padrão que resolve é gerar uma chave própria por mensagem, gravá-la no seu banco antes de chamar a API e só disparar se aquela chave ainda não tiver sido enviada. O campo Id do envio de texto ajuda nessa conciliação: você define o identificador, casa com o seu registro e reconhece nos eventos de entrega qual mensagem é qual.
Rate limit é o teto de requisições aceitas em uma janela de tempo. No contexto de WhatsApp, porém, o limite que realmente importa não é técnico e sim comportamental: o que aumenta o risco para o número é o padrão de disparo — muitas mensagens em sequência, sem intervalo, para contatos que não esperavam receber. Um ritmo parecido com o humano protege mais do que qualquer configuração — e no zapon esse ritmo não fica por sua conta: o servidor cumpre uma pausa aleatória de 8 a 20 segundos entre as mensagens de um mesmo número e aplica uma cota de 300 envios por dia para cada número, com aviso ao cruzar 80%, 90%, 95% e 100% e resposta 429 quando a cota do dia acaba. O preço continua sendo por número conectado, sem cobrança por mensagem: a cota é trava de proteção, não teto comercial.
Como um número de WhatsApp entra no ar, como ele é identificado e o que acontece quando a sessão cai.
Conexão é um número de WhatsApp vinculado à sua conta, com token, webhook e configurações próprios. É a unidade de isolamento e de cobrança do zapon: cada número é uma conexão independente, e o que acontece em uma não afeta as outras. Instância é o nome que boa parte do mercado dá para a mesma coisa — cada número conectado, separado dos demais — e no zapon corresponde exatamente a uma conexão. Você cria quantas precisar na mesma conta, sem degrau de plano. Trocar o token no header é como o seu código escolhe de qual número sai cada mensagem.
Sessão é o estado autenticado de um número junto ao WhatsApp, o vínculo que permanece depois que o QR Code é lido. Enquanto a sessão está ativa, a conexão envia e recebe mensagens. Ela pode cair por instabilidade de rede e voltar sozinha, ou ser encerrada de vez pelo WhatsApp — nesse caso é preciso ler um novo QR Code, e o token da conexão continua o mesmo. Esse estado não é controlado por endpoint da API: conectar, desconectar, sair da sessão e acompanhar o status são ações do painel do zapon, na tela de Conexões, onde o QR Code é exibido. Repare na diferença entre as duas saídas: desconectar interrompe a sessão mantendo o pareamento, enquanto sair da sessão desfaz o pareamento e exige nova leitura do código. A API que você integra é a de uso — /chat/*, /group/* e /user/* — e ela só responde enquanto a sessão está de pé.
QR Code é o código gráfico exibido no painel que o aplicativo do WhatsApp lê para autorizar a conexão do número à API. O caminho no celular é o mesmo do WhatsApp Web: abrir o WhatsApp do número, ir em Aparelhos conectados, tocar em Conectar um aparelho e apontar a câmera para a tela. Não há cadastro comercial, fila de aprovação nem verificação prévia a atravessar. O código tem validade curta e é gerado de novo quando expira, sempre na própria tela do painel — ele não é entregue por webhook, porque QR não é um evento. Depois de pareado, o número segue conectado sem repetir a leitura, a menos que a sessão seja encerrada.
Código de pareamento é a alternativa ao QR Code: em vez de escanear a tela, você gera um código de oito dígitos e o digita no WhatsApp do número, em Aparelhos conectados → Conectar um aparelho → Conectar com número de telefone. Serve quando não dá para apontar a câmera para a tela, como em instalação remota, servidor sem interface gráfica ou celular sem acesso à imagem do painel. O resultado é idêntico ao do QR Code: a mesma sessão, o mesmo token e o mesmo comportamento depois de pareado. O código é gerado no painel do zapon, na mesma tela de Conexões em que aparece o QR Code.
WhatsApp Web é o modo de uso em que um número é operado por outro aparelho autorizado, e multidispositivo é o recurso do WhatsApp que permite manter vários desses aparelhos ligados ao mesmo número, sem depender de o celular estar online. É essa base que as APIs conectadas por QR Code utilizam: a conexão da API ocupa uma das vagas de aparelho conectado, como se fosse mais um navegador autorizado. As consequências práticas importam — o número continua funcionando normalmente no celular, o histórico da conversa é o mesmo e revogar o aparelho dentro do aplicativo derruba a conexão da API na hora.
JID (WhatsApp ID) é o identificador interno que o WhatsApp usa para endereçar um contato ou um grupo. Contatos aparecem como o número seguido de @s.whatsapp.net; grupos, como um identificador longo seguido de @g.us. Você encontra JIDs nos payloads de evento, no retorno de GET /group/list e nos campos que apontam para o autor de uma mensagem. Nos envios, o campo Phone aceita tanto o número em formato internacional quanto o JID completo, e para enviar a um grupo é o JID do grupo que vai nesse campo. Menções dentro de uma mensagem também exigem o JID completo de quem é mencionado.
Número em formato internacional é o telefone escrito com código do país, DDD e número, apenas dígitos, sem sinal de mais, espaço, parêntese ou traço: 5511999999999. É esse o formato que o campo Phone espera em todos os endpoints de envio. O erro aqui é a causa silenciosa mais comum de integração que não entrega: o número sai do banco com máscara de formatação, ou sem o código do país, e a chamada falha ou vai para o destino errado. Normalize antes de enviar, removendo tudo que não for dígito e garantindo o 55. Para confirmar que o destino existe no WhatsApp, use POST /user/check.
O que a API envia, o que ela recebe de volta e como pedir resposta estruturada em vez de texto livre.
Mensagem de texto é o envio mais simples da API: um POST para /chat/send/text com dois campos obrigatórios, Phone e Body. A resposta traz o identificador da mensagem, que vale guardar para casar depois com os eventos de entrega e leitura. Três campos opcionais mudam o comportamento: LinkPreview gera a prévia visual quando o texto tem link e vem desligado por padrão; Id permite definir o seu próprio identificador, útil para conciliar com o seu banco; e ContextInfo faz a mensagem responder a uma mensagem específica, citando-a. Os exemplos em cURL, Node e Python estão em Primeiro envio.
Mídia é qualquer conteúdo que não seja texto puro: imagem, vídeo, áudio, documento, figurinha, localização e cartão de contato. Cada tipo tem o próprio endpoint — /chat/send/image, /chat/send/video, /chat/send/audio, /chat/send/document, /chat/send/sticker, /chat/send/location e /chat/send/contact —, e imagem aceita legenda. No sentido inverso, a mídia recebida não chega decodificada no payload do evento: você usa os endpoints de download correspondentes, como /chat/downloadimage e /chat/downloadaudio, para obter o arquivo. Documento é o caminho para boleto, nota fiscal, contrato e comprovante, o uso mais frequente de mídia em integração de negócio.
Template é uma mensagem com estrutura definida, montada a partir de um modelo com partes fixas e partes variáveis. Na via oficial, o termo tem sentido regulatório: é um modelo aprovado previamente, sem o qual não se inicia conversa fora da janela de atendimento. Em conexões feitas por QR Code não existe essa aprovação prévia — o endpoint POST /chat/send/template envia uma mensagem em formato de template, com os elementos estruturados que ele suporta, sem fila de homologação. Fora desses dois sentidos, muita gente usa a palavra apenas como sinônimo de texto padronizado com variáveis, montado no próprio código antes do envio.
Botões de resposta e lista de opções são as duas formas de pedir resposta estruturada em vez de texto livre. Botões (POST /chat/send/buttons) exibem alternativas tocáveis junto da mensagem; a lista (POST /chat/send/list) abre um menu de itens selecionáveis, indicado quando as opções são muitas para caber em botões. Nos dois casos a resposta chega no seu webhook já identificando o que foi escolhido, o que elimina a interpretação de texto livre e, junto com ela, os erros de digitação que travam fluxos automatizados. É a diferença entre pedir “digite 1 para confirmar” e deixar a pessoa tocar em Confirmar. Além da resposta rápida, o mesmo endpoint monta botão que abre um link ("type": "cta_url"), botão que abre o discador ("type": "cta_call") e botão que copia um código ("type": "copy") — e os tipos convivem na mesma mensagem. O toque em resposta rápida volta no webhook; os outros três agem no aparelho de quem recebe.
Enquete é a mensagem com pergunta e opções de voto, enviada por POST /chat/send/poll. Diferente dos botões, ela é feita para coletar escolhas de várias pessoas — o uso típico é em grupo — e o WhatsApp exibe o resultado agregado dentro da própria conversa. Serve para confirmar presença, escolher horário ou medir preferência sem montar formulário externo. Como todo envio, aceita o campo Phone com o número do contato ou com o JID do grupo. Vale lembrar que enquete é recurso de conversa, não instrumento de pesquisa formal: não há garantia de resposta, e a visibilidade do voto segue as regras do próprio WhatsApp.
Reação é o emoji aplicado a uma mensagem específica, sem gerar uma nova mensagem na conversa. Na API, é um POST para /chat/react informando a qual mensagem a reação se refere, com o prefixo me: quando a mensagem é sua. É o recurso mais barato de acusar recebimento em fluxo automatizado: o robô reage com um visto para sinalizar que a solicitação entrou na fila, sem poluir o histórico com um “recebemos sua mensagem”. Enviar reação vazia remove a anterior. Reações recebidas também chegam pelo webhook, o que permite usá-las como confirmação em fluxos simples.
Confirmação de entrega indica que a mensagem chegou ao aparelho do destinatário; confirmação de leitura indica que ela foi aberta. São os dois tiques cinzas e os dois tiques azuis do aplicativo, expostos como eventos de webhook: ReadReceipt entrega esses recibos e Receipt traz os de baixo nível. Para usá-los, guarde o identificador devolvido no envio e case com o identificador que vem no evento. É assim que se monta um painel honesto de entrega: sem esse casamento, o máximo que você sabe é que a API aceitou a requisição, o que não é a mesma coisa que a pessoa ter recebido. A leitura depende da configuração de privacidade do destinatário e pode simplesmente não vir.
Presença é o estado visível de atividade em uma conversa: online, offline, digitando ou gravando áudio. A API atua nos dois sentidos. Você sinaliza a sua com POST /chat/presence, o que dá ritmo humano a um fluxo automatizado, já que mostrar “digitando” por um instante antes de responder evita a resposta instantânea que denuncia robô. E observa a dos outros pelos eventos Presence, quando um contato fica online ou offline, e ChatPresence, quando começa ou para de digitar. POST /user/presence define a presença geral do seu número. Nada disso é obrigatório para enviar, mas muda a percepção de quem recebe.
Endereçamento, administração e entrada em conversas coletivas pela API.
Grupo é a conversa coletiva do WhatsApp, endereçada por um JID terminado em @g.us. Para enviar a um grupo, use esse JID no campo Phone dos mesmos endpoints de envio: não existe endpoint separado de mensagem de grupo. Para administrar, existe um conjunto próprio — GET /group/list lista os grupos do número, /group/create cria, /group/info detalha, /group/name, /group/topic e /group/photo alteram a identidade, e /group/announce, /group/locked e /group/ephemeral controlam quem fala, quem edita e se as mensagens somem. A referência está em Grupos.
Participante é cada número que integra um grupo, com papel de membro ou de administrador. POST /group/updateparticipants é o endpoint único para as quatro operações: adicionar, remover, promover a administrador e rebaixar a membro. Duas restrições valem lembrar antes de automatizar: o número conectado precisa ser administrador do grupo para alterar a composição, e as configurações de privacidade de cada pessoa podem impedir que ela seja adicionada por quem não está na agenda dela — nesse caso, o caminho é enviar o link de convite. Quando o grupo exige aprovação para entrar, os pedidos pendentes ficam em GET /group/requestparticipants.
Link de convite é o endereço que permite entrar em um grupo sem ser adicionado diretamente por um administrador. GET /group/invitelink devolve o link atual e também permite gerar um novo, o que invalida o anterior — é o botão de emergência quando um convite vaza. POST /group/join usa um link para entrar em um grupo e POST /group/inviteinfo consulta os dados do convite antes de aceitar. Na prática, o link é o caminho recomendado para montar grupos com clientes: contorna as restrições de privacidade que bloqueiam a adição direta e transforma a entrada em ato voluntário, o que é melhor do ponto de vista de consentimento.
Como o seu sistema fica sabendo do que acontece no número conectado.
Webhook é uma URL pública do seu sistema que recebe eventos automaticamente, por POST, assim que eles acontecem. É o inverso da consulta: em vez de você perguntar se chegou mensagem, o zapon avisa. Você cadastra uma URL por conexão no painel e marca quais eventos quer receber. O corpo do POST traz o evento completo, então não é preciso uma segunda chamada para descobrir o conteúdo. A sua URL só precisa aceitar POST e responder rápido: aceite o evento, devolva 200 e faça o processamento pesado em segundo plano, porque demora na resposta pode ser contada como falha de entrega. Detalhes em Receber mensagens.
Evento é cada acontecimento que o WhatsApp reporta e que o zapon entrega no seu webhook. São 38 no total, divididos em seis famílias: mensagens (Message, ReadReceipt, UndecryptableMessage, MediaRetry, FBMessage), conexão (Connected, Disconnected, LoggedOut, ConnectFailure, TemporaryBan, PairSuccess e outros), presença (Presence, ChatPresence), grupos e contatos (GroupInfo, JoinedGroup, Picture, BlocklistChange), chamadas (CallOffer, CallTerminate e outros) e sincronização (HistorySync, OfflineSyncCompleted, OfflineSyncPreview). Repare que o QR Code não é evento de webhook — ele aparece na tela de conexão do painel — e que o recibo de entrega e leitura chama ReadReceipt: não existe evento Receipt. Você escolhe quais assinar, por conexão, e só recebe o que assinou. Marcar apenas o que o seu fluxo usa reduz ruído no endpoint e facilita a depuração. Para acompanhar a saúde do número, os eventos de conexão são o caminho: Disconnected avisa a queda e LoggedOut avisa que o número precisa reler o QR Code. A lista completa está em Eventos disponíveis.
Polling é consultar a API repetidamente para descobrir se algo mudou, em vez de ser avisado. É o oposto do webhook e quase sempre a escolha pior: gera chamadas que na maioria das vezes voltam sem novidade e introduz um atraso do tamanho do intervalo entre as consultas. Ainda assim tem lugar legítimo. Sem uma URL pública para receber eventos, o polling é o único caminho: GET /chat/history recupera as mensagens de uma conversa a cada consulta. O próprio painel usa essa ideia ao atualizar o estado das conexões a cada dez segundos enquanto a página está aberta.
O que determina se um número sobrevive a uma operação automatizada.
Aquecimento é a prática de aumentar o volume de um número novo aos poucos, em vez de começar disparando em escala. Um chip recém-ativado que envia centenas de mensagens no primeiro dia apresenta um padrão que se distingue com facilidade do uso humano, e é o padrão, não o total, que chama atenção. O aquecimento não é uma configuração e não existe botão para ligá-lo: é a sua fila de envio crescendo ao longo de dias, com conversas de duas vias no meio e não apenas mensagens saindo. Vale combinar com um número dedicado à automação, em vez do número pessoal ou do número principal do negócio.
Banimento é o encerramento da conta de WhatsApp de um número pela própria plataforma; bloqueio temporário é a suspensão por prazo determinado, sinalizada pelo evento TemporaryBan. Os dois riscos existem em qualquer API de WhatsApp, oficial ou não: a decisão é da plataforma sobre o número, e nenhum fornecedor de integração controla essa decisão. Quem promete que o número nunca será bloqueado não está sendo honesto. O que existe é redução de risco — enviar apenas para quem espera receber, espaçar os disparos, verificar os números antes com POST /user/check, oferecer saída e aquecer número novo. Denúncia de destinatário é o fator que mais pesa. As práticas estão em Preservar o número.
Consentimento, lei brasileira e as diferenças entre as vias de acesso ao WhatsApp.
Opt-in é o consentimento de quem passa a receber suas mensagens; opt-out é a saída, o pedido de parar de receber. Os dois são exigência prática e jurídica ao mesmo tempo. Do lado prático, mensagem para quem não pediu contato é a causa mais comum de denúncia, e denúncia é o que leva a bloqueio. Do lado jurídico, tratar dado pessoal sem base legal e sem via de saída é exatamente o que a legislação de proteção de dados reprova. Implementar é simples: registre onde e quando cada contato consentiu, ofereça uma forma óbvia de sair — uma palavra-chave reconhecida pelo seu fluxo já resolve — e honre o pedido no mesmo dia, sem etapa de convencimento.
LGPD é a Lei Geral de Proteção de Dados brasileira, que regula o tratamento de dados pessoais e alcança diretamente quem envia mensagens de WhatsApp em nome de uma empresa. Número de telefone é dado pessoal, e o conteúdo da conversa costuma ser também. Três obrigações aparecem em toda integração: ter base legal para o contato, em geral consentimento ou execução de contrato; informar a finalidade de forma clara; e atender pedidos de saída e de exclusão. Some a isso guardar o mínimo necessário, pelo tempo necessário, e proteger o que foi guardado. Quem dispara para lista comprada não tem base legal, e a ausência dela não se corrige com aviso no rodapé.
API oficial é a via homologada pelo WhatsApp para empresas, com cadastro comercial, verificação do negócio, catálogo de modelos de mensagem aprovados previamente e cobrança por conversa. API não oficial é o nome de categoria dado às integrações que conectam um número comum por QR Code, usando o mesmo mecanismo de aparelho autorizado do WhatsApp Web, sem homologação e sem cobrança por conversa. As diferenças que pesam na decisão: a via oficial exige processo e tem custo por volume, mas oferece selo e previsibilidade contratual; a conectada por QR Code entra no ar em minutos, envia de um número que os clientes já conhecem e não impõe modelos aprovados. O risco de bloqueio do número existe nas duas.
BSP (Business Solution Provider) é a empresa credenciada a revender e operar o acesso à API oficial do WhatsApp. Quem escolhe a via oficial normalmente contrata por meio de um BSP, que intermedia o cadastro, a verificação do negócio, a aprovação dos modelos de mensagem e o faturamento por conversa. É por isso que o preço da via oficial costuma ter duas camadas: o que a plataforma cobra por conversa e o que o intermediário cobra pelo serviço. Integrações conectadas por QR Code não passam por BSP, porque não existe credenciamento a intermediar — o que remove uma camada de custo e, junto com ela, a figura do intermediário responsável.
Chatbot é o programa que responde automaticamente às mensagens recebidas; fluxo conversacional é o desenho das perguntas, respostas e caminhos que ele segue. O ciclo técnico é sempre o mesmo: o webhook ouve, a sua lógica decide e um endpoint de envio responde. O que separa um bot útil de um irritante é o fluxo, não o código — perguntas curtas, opções em botões em vez de texto livre, memória do que já foi respondido e, acima de tudo, uma saída explícita para falar com uma pessoa. Um bot que não sabe transferir para humano vira obstáculo. O atendimento em si continua acontecendo no WhatsApp, com as pessoas do seu time. No zapon, esse fluxo não precisa de código: o chatbot de menus com botões é montado no painel por uma entrevista guiada, que pergunta o que o seu negócio responde todo dia e transforma as respostas no menu.
MCP (Model Context Protocol) é o protocolo aberto pelo qual um assistente de IA descobre e usa ferramentas externas. Em vez de você escrever a integração, o assistente recebe a lista de ações disponíveis e passa a executá-las quando a conversa pede. No zapon, o conector MCP expõe o seu número como ferramenta: você pede o envio em linguagem natural e a mensagem sai pelo número conectado. Funciona com o Claude, com o ChatGPT em modo desenvolvedor, com o Codex CLI e com o Gemini CLI — o aplicativo web do Gemini ainda não suporta o protocolo. As travas de proteção continuam do lado do servidor: a mesma pausa entre envios e a mesma cota diária valem para o que o assistente pedir.
É uma interface que permite enviar e receber mensagens de WhatsApp a partir de um sistema, por requisições HTTP, sem usar o aplicativo manualmente. Na prática, o seu software faz um POST com o número de destino e o conteúdo, e recebe de volta o identificador da mensagem.
É uma URL pública do seu sistema que recebe automaticamente os eventos do número conectado, como mensagens recebidas, por POST. O evento chega completo no corpo da requisição, então não é preciso fazer uma segunda chamada para descobrir o conteúdo.
No webhook a API avisa o seu sistema assim que o evento acontece; no polling o seu sistema pergunta repetidamente se algo mudou. O webhook entrega em tempo real e gasta menos chamadas; o polling só compensa quando você não tem uma URL pública para receber eventos.
Conexão e instância são o mesmo conceito com nomes diferentes: um número de WhatsApp vinculado à conta, com token e webhook próprios. Sessão é o estado autenticado desse número junto ao WhatsApp, que pode cair e voltar sem que a conexão deixe de existir.
A via oficial é homologada pelo WhatsApp e exige cadastro comercial, verificação, modelos de mensagem aprovados previamente e cobrança por conversa. A não oficial conecta um número comum por QR Code, como o WhatsApp Web, sem homologação e sem cobrança por conversa. O risco de bloqueio do número existe nas duas.
JID é o identificador interno do WhatsApp para um contato ou um grupo: contatos terminam em @s.whatsapp.net e grupos em @g.us. Você precisa dele para enviar mensagem a um grupo e para mencionar alguém dentro de uma mensagem.
São duas formas de autorizar a mesma conexão. No QR Code você escaneia a imagem do painel com a câmera do celular; no código de pareamento você digita um código de oito dígitos no WhatsApp do número. O resultado é idêntico: a mesma sessão e o mesmo token.
É o teto de requisições aceitas em uma janela de tempo. No zapon existe um teto explícito de proteção: 300 mensagens por dia por número, com pausa de 8 a 20 segundos entre os envios cumprida pelo servidor. Ainda assim, o limite que mais pesa é comportamental — disparar para quem não esperava receber aumenta o risco para o número mesmo dentro da cota.
Botões exibem alternativas tocáveis junto da mensagem e servem para poucas escolhas; a lista abre um menu de itens selecionáveis e comporta mais opções. Nos dois casos a resposta chega no webhook já identificando o que foi escolhido.
Opt-in é o consentimento de quem passa a receber suas mensagens. Importa por dois motivos: mensagem para quem não pediu contato é a causa mais comum de denúncia, que leva a bloqueio do número, e o tratamento de dado pessoal sem base legal contraria a legislação de proteção de dados.
14 dias grátis, sem cartão. Crie a conta, leia o QR Code e chame a API — sem cobrança por mensagem.