{"id":100,"date":"2026-08-31T19:19:19","date_gmt":"2026-08-31T22:19:19","guid":{"rendered":"https:\/\/postping.com.br\/blog\/webhook-whatsapp-api-oficial\/"},"modified":"2026-08-31T19:20:38","modified_gmt":"2026-08-31T22:20:38","slug":"webhook-whatsapp-api-oficial","status":"publish","type":"post","link":"https:\/\/postping.com.br\/blog\/webhook-whatsapp-api-oficial\/","title":{"rendered":"Webhook do WhatsApp e os limites da API oficial da Meta"},"content":{"rendered":"<p>Webhook do WhatsApp existe, funciona, e n\u00e3o serve para avisar ningu\u00e9m sobre o seu artigo novo. Na plataforma oficial da Meta, webhook \u00e9 o canal pelo qual o WhatsApp fala com o seu servidor: mensagem que chegou, status de entrega, template que mudou de situa\u00e7\u00e3o. A dire\u00e7\u00e3o \u00e9 essa, e s\u00f3 essa. Quando algu\u00e9m vende \u201cwebhook do WhatsApp\u201d com a mesma cara do webhook do Discord, uma URL que voc\u00ea cola num campo do painel e pronto, est\u00e1 vendendo outra coisa com o nome errado. A diferen\u00e7a aparece no primeiro dia de uso, n\u00e3o no terceiro m\u00eas.<\/p>\n<h2>A palavra troca de lado quando chega no WhatsApp<\/h2>\n<p>No Discord e no Telegram, o webhook \u00e9 a porta de sa\u00edda. Seu WordPress publica um artigo, dispara um <code>POST<\/code> para um endere\u00e7o, e a mensagem aparece no canal. Voc\u00ea n\u00e3o precisa de servidor pr\u00f3prio para receber nada, porque nada volta.<\/p>\n<p>A documenta\u00e7\u00e3o da Cloud API descreve o oposto com todas as letras: webhooks s\u00e3o requisi\u00e7\u00f5es HTTP com corpo JSON que os servidores da Meta enviam para um servidor da sua escolha. S\u00e3o <strong>21<\/strong> campos que d\u00e1 para assinar, e os nomes dizem a natureza deles: <code>messages<\/code> para mensagem recebida, <code>message_template_status_update<\/code> para quando um template muda de situa\u00e7\u00e3o, <code>message_template_quality_update<\/code> e <code>phone_number_quality_update<\/code> para queda de qualidade, <code>account_update<\/code> para mudan\u00e7a na conta. Nenhum deles envia coisa alguma para um usu\u00e1rio. Todos avisam voc\u00ea de algo que j\u00e1 aconteceu.<\/p>\n<p>Isso muda a natureza do que voc\u00ea precisa manter no ar. Para receber webhook da Meta, o endpoint tem que ser HTTPS, aceitar <code>POST<\/code>, responder o desafio de verifica\u00e7\u00e3o na configura\u00e7\u00e3o do app e carregar a permiss\u00e3o certa: <code>whatsapp_business_messaging<\/code> para o campo de mensagens, <code>whatsapp_business_management<\/code> para os outros. O corpo pode chegar com at\u00e9 <strong>3 MB<\/strong>. Se o seu servidor devolver qualquer coisa que n\u00e3o seja 200, a Meta repete a entrega com frequ\u00eancia decrescente por at\u00e9 <strong>7 dias<\/strong>, e a pr\u00f3pria documenta\u00e7\u00e3o avisa que notifica\u00e7\u00f5es duplicadas acontecem durante essas repeti\u00e7\u00f5es.<\/p>\n<p>Um endpoint que precisa ficar de p\u00e9, tratar repeti\u00e7\u00e3o e detectar duplicata \u00e9 infraestrutura de atendimento. Quem tem blog n\u00e3o est\u00e1 procurando isso.<\/p>\n<h2>O que a plataforma exige antes da primeira mensagem sair<\/h2>\n<p>Mandar mensagem \u00e9 outro caminho, com outro endere\u00e7o: <code>POST \/&lt;WHATSAPP_BUSINESS_PHONE_NUMBER_ID&gt;\/messages<\/code>. E ele n\u00e3o \u00e9 livre.<\/p>\n<p>A primeira trava \u00e9 o consentimento. A pol\u00edtica de mensagens do WhatsApp Business condiciona qualquer contato a duas coisas ao mesmo tempo: a pessoa ter dado o n\u00famero dela para voc\u00ea, e voc\u00ea ter recebido opt-in confirmando que ela quer receber suas mensagens. A pol\u00edtica pede opt-in separado por categoria de mensagem, e n\u00e3o trata isso como recomenda\u00e7\u00e3o.<\/p>\n<p>A segunda trava \u00e9 a janela. Quando um usu\u00e1rio manda mensagem para o seu n\u00famero, come\u00e7a um cron\u00f4metro de <strong>24 horas<\/strong> que a documenta\u00e7\u00e3o chama de janela de atendimento; se a pessoa escrever de novo antes de expirar, o cron\u00f4metro volta para 24 horas. Dentro da janela, voc\u00ea envia qualquer tipo de mensagem sem aprova\u00e7\u00e3o pr\u00e9via. Fora dela, s\u00f3 template aprovado. A tentativa de mandar mensagem comum depois disso volta com o erro <code>131047<\/code>, cujo texto \u00e9 literalmente que passaram mais de 24 horas desde a \u00faltima resposta do destinat\u00e1rio. Template que n\u00e3o existe naquele idioma, ou que n\u00e3o foi aprovado, volta como <code>132001<\/code>.<\/p>\n<p>Repare no que essas duas travas fazem juntas com o caso do blog. Seu leitor nunca mandou mensagem para voc\u00ea. Ele leu um artigo. A janela de atendimento dele nunca abriu, e n\u00e3o abre por causa de uma publica\u00e7\u00e3o, ent\u00e3o cem por cento dos avisos de conte\u00fado novo caem do lado de fora dela e precisam ser template aprovado.<\/p>\n<p>H\u00e1 ainda um limite de ritmo por par de n\u00fameros, de <strong>1 mensagem a cada 6 segundos<\/strong> para o mesmo usu\u00e1rio, e um teto de vaz\u00e3o da pr\u00f3pria Cloud API que aparece como <code>130429<\/code> quando estourado. Para uma lista de trezentos leitores, esses dois n\u00fameros deixam de ser detalhe.<\/p>\n<p>E o endere\u00e7o em si n\u00e3o \u00e9 est\u00e1vel para sempre. A chamada \u00e9 versionada, e o changelog da Graph API mostra o ritmo: a v26.0 saiu em <strong>29 de julho de 2026<\/strong>, a v25.0 em 18 de fevereiro de 2026 com validade at\u00e9 <strong>29 de julho de 2028<\/strong>, e a v24.0 em outubro de 2025 com validade at\u00e9 fevereiro de 2028. Cada vers\u00e3o vive cerca de dois anos. Quem integra assume uma migra\u00e7\u00e3o recorrente, que \u00e9 exatamente o tipo de manuten\u00e7\u00e3o que ningu\u00e9m or\u00e7a quando o combinado com o cliente era \u201cavisar quando sair post novo\u201d.<\/p>\n<h2>O template tem estado, e o estado muda sem voc\u00ea mexer<\/h2>\n<p>A parte que o discurso comercial mais esconde \u00e9 que template n\u00e3o \u00e9 campo de texto: \u00e9 um objeto com situa\u00e7\u00e3o, revis\u00e3o e hist\u00f3rico de qualidade.<\/p>\n<p>Todo template passa por revis\u00e3o autom\u00e1tica ao ser criado ou editado. Aprovado, a situa\u00e7\u00e3o vai para <code>APPROVED<\/code> e ele pode ser usado. Reprovado, vira <code>REJECTED<\/code>. E existem dois estados que n\u00e3o dependem de nada que voc\u00ea fa\u00e7a depois: <code>PAUSED<\/code>, quando o template \u00e9 desativado por retorno negativo dos usu\u00e1rios ou baixo engajamento, e <code>DISABLED<\/code>, quando ele \u00e9 desativado em definitivo depois de pausas repetidas. No envio, esses estados aparecem como <code>132015<\/code> para template pausado por baixa qualidade e <code>132016<\/code> para template desabilitado de vez, caso em que a orienta\u00e7\u00e3o da pr\u00f3pria documenta\u00e7\u00e3o \u00e9 criar outro, com conte\u00fado diferente. A qualidade que decide isso \u00e9 classificada em alta, m\u00e9dia e baixa, a partir de engajamento e retorno de quem recebe.<\/p>\n<p>Os tetos de quantidade seguem a verifica\u00e7\u00e3o do neg\u00f3cio. Portf\u00f3lio n\u00e3o verificado fica limitado a <strong>250<\/strong> templates por conta do WhatsApp Business; portf\u00f3lio verificado com nome de exibi\u00e7\u00e3o aprovado sobe para <strong>6.000<\/strong>. Em qualquer um dos dois, d\u00e1 para criar no m\u00e1ximo <strong>100<\/strong> templates por conta por hora.<\/p>\n<p>E tem a conta. Desde <strong>1\u00ba de julho de 2025<\/strong>, a Meta cobra por mensagem, e n\u00e3o mais por conversa: a cobran\u00e7a acontece quando um template \u00e9 entregue. Mensagem que n\u00e3o \u00e9 template, enviada dentro de uma janela de atendimento aberta, n\u00e3o custa nada. Template de utilidade e de autentica\u00e7\u00e3o tamb\u00e9m sai de gra\u00e7a dentro da janela. J\u00e1 a categoria de marketing \u00e9 cobrada sempre que entregue fora da janela, e as tarifas variam por categoria, por c\u00f3digo de pa\u00eds do destinat\u00e1rio e por faixa de volume mensal, com atualiza\u00e7\u00e3o trimestral no primeiro dia de cada trimestre. Existe tamb\u00e9m a janela de ponto de entrada gratuito, de <strong>72 horas<\/strong>, aberta por an\u00fancios de clique para o WhatsApp e por bot\u00e3o de p\u00e1gina.<\/p>\n<p>Pagar tamb\u00e9m n\u00e3o garante entrega. Existe um erro espec\u00edfico, o <code>131049<\/code>, para quando a Meta bloqueia a entrega a fim de preservar o engajamento saud\u00e1vel da plataforma, por conta de um limite de templates de marketing por usu\u00e1rio; a orienta\u00e7\u00e3o para ele \u00e9 esperar mais de 24 horas antes de tentar de novo com aquela pessoa. Quer dizer que a mesma mensagem pode ser aprovada, cobrada e ainda assim segurada, com base em quanta coisa de marketing aquele destinat\u00e1rio j\u00e1 recebeu. Ao lado dele h\u00e1 o <code>131042<\/code>, que \u00e9 falha do meio de pagamento: sem cobran\u00e7a configurada e funcionando, o envio simplesmente para.<\/p>\n<p>Um template que diz \u201csaiu artigo novo no blog\u201d \u00e9 marketing. Ele nasce na \u00fanica categoria que \u00e9 cobrada em todo envio fora da janela, e \u00e9 justamente a categoria que as pessoas mais bloqueiam. Quer dizer que o mesmo aviso que voc\u00ea quer automatizar \u00e9, ao mesmo tempo, o que mais custa e o que mais corre risco de ser pausado por qualidade.<\/p>\n<h2>Onde o argumento contr\u00e1rio \u00e9 mais forte<\/h2>\n<p>A obje\u00e7\u00e3o s\u00e9ria n\u00e3o \u00e9 nenhuma dessas. \u00c9 que a plataforma exp\u00f5e hoje uma Groups API, na Cloud API, e com ela o n\u00famero comercial cria grupo e manda mensagem dentro dele. Isso \u00e9 verdade, \u00e9 oficial, e mudou a conversa: d\u00e1 para criar, listar e atualizar grupos, enviar texto, m\u00eddia, template de texto e template com m\u00eddia, gerar e redefinir o link de convite, aprovar ou recusar pedidos de entrada. O teto \u00e9 de <strong>10.000<\/strong> grupos por n\u00famero comercial.<\/p>\n<p>O problema est\u00e1 no n\u00famero que decide o uso: o m\u00e1ximo de participantes por grupo \u00e9 <strong>8<\/strong>. A documenta\u00e7\u00e3o tamb\u00e9m \u00e9 expl\u00edcita em dizer que n\u00e3o existe endpoint para adicionar participante direto; a entrada acontece por link de convite, com a pessoa aceitando. Some a isso os pr\u00e9-requisitos, que exigem Official Business Account e excluem n\u00fameros do aplicativo WhatsApp Business e n\u00fameros em Multi-solution Conversations, mais a lista do que n\u00e3o passa dentro do grupo: chamada, mensagem tempor\u00e1ria, visualiza\u00e7\u00e3o \u00fanica, autentica\u00e7\u00e3o, com\u00e9rcio e mensagem interativa.<\/p>\n<p>Oito pessoas que precisam aceitar um convite \u00e9 uma sala de trabalho. Serve muito bem para a equipe interna de uma ag\u00eancia acompanhar um cliente. N\u00e3o \u00e9 canal de comunidade, e n\u00e3o \u00e9 lista de leitores. A Groups API responde \u201cd\u00e1 para mandar no grupo?\u201d com sim, e responde \u201cd\u00e1 para avisar minha audi\u00eancia?\u201d com n\u00e3o, e as duas respostas convivem sem contradi\u00e7\u00e3o.<\/p>\n<p>Sobra a obje\u00e7\u00e3o mais desconfort\u00e1vel: as APIs n\u00e3o oficiais fazem tudo isso. Fazem mesmo. Elas mandam para grupo grande, dispensam template, ignoram janela e n\u00e3o cobram por mensagem entregue, porque conversam com o WhatsApp por fora. O pre\u00e7o est\u00e1 escrito na pol\u00edtica de mensagens: operar um servi\u00e7o que usa o WhatsApp em viola\u00e7\u00e3o dos termos, como mandar mensagem em escala de forma n\u00e3o autorizada, d\u00e1 \u00e0 empresa o direito de limitar ou remover seu acesso aos servi\u00e7os do WhatsApp Business. E a pol\u00edtica vai al\u00e9m da conta encerrada, dizendo que uma conta terminada por viola\u00e7\u00e3o pode levar \u00e0 proibi\u00e7\u00e3o de todo uso futuro dos produtos e servi\u00e7os do WhatsApp pela pessoa e pela organiza\u00e7\u00e3o dela. No lado t\u00e9cnico, a conta restringida por pol\u00edtica aparece como <code>368<\/code>. Quem opera as redes de um cliente e perde o n\u00famero dele nessa conta n\u00e3o perde uma automa\u00e7\u00e3o: perde o cliente.<\/p>\n<p>A terceira obje\u00e7\u00e3o \u00e9 a \u00fanica que nenhuma documenta\u00e7\u00e3o responde, e por isso a mais honesta: sua audi\u00eancia est\u00e1 no WhatsApp, n\u00e3o no Discord. \u00c9 verdade em boa parte do Brasil, e n\u00e3o adianta discutir.<\/p>\n<h2>O que sobra de p\u00e9 para quem publica toda semana<\/h2>\n<p>Avisar a equipe e a comunidade a cada publica\u00e7\u00e3o \u00e9 problema de sa\u00edda, e Discord e Telegram resolvem sa\u00edda: o webhook do Discord aceita a mensagem sem template, sem janela, sem revis\u00e3o, e o bot do Telegram entrega em grupo e canal do mesmo jeito. \u00c9 por isso que o Post Ping avisa esses dois canais a cada artigo publicado, e n\u00e3o o WhatsApp. A documenta\u00e7\u00e3o de cada plataforma decide isso muito antes da prefer\u00eancia de quem integra. O detalhe de como ler um erro quando esse disparo falha est\u00e1 em <a href=\"https:\/\/postping.com.br\/blog\/erro-webhook-401-404-429\/\">erro de webhook no WordPress<\/a>.<\/p>\n<p>Para o WhatsApp, o caminho que continua de p\u00e9 \u00e9 o link, n\u00e3o o disparo. A pessoa que conversa com voc\u00ea no WhatsApp j\u00e1 abriu a janela sozinha, e nesse momento uma mensagem comum com o endere\u00e7o do artigo \u00e9 gratuita e n\u00e3o precisa de aprova\u00e7\u00e3o nenhuma. O que ajuda a\u00ed \u00e9 ter um endere\u00e7o est\u00e1vel para mandar, no seu dom\u00ednio, que se atualiza sozinho quando voc\u00ea publica. \u00c9 a mesma p\u00e1gina que serve de link na bio do Instagram, e ningu\u00e9m precisa aprovar template para mandar um link numa conversa que a pr\u00f3pria pessoa come\u00e7ou.<\/p>\n<p>Se o que voc\u00ea procurava era a vers\u00e3o do WhatsApp daquele campo onde se cola uma URL e a mensagem chega, ela n\u00e3o existe na plataforma oficial, e provavelmente n\u00e3o vai existir: as travas de opt-in, janela e template s\u00e3o o modelo de neg\u00f3cio, n\u00e3o uma limita\u00e7\u00e3o t\u00e9cnica esperando ser removida. O conceito que resolve o seu caso \u00e9 o outro, e ele est\u00e1 explicado do come\u00e7o em <a href=\"https:\/\/postping.com.br\/blog\/o-que-e-webhook\/\">o que \u00e9 um webhook<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Webhook do WhatsApp \u00e9 de entrada: a Meta avisa voc\u00ea, n\u00e3o o contr\u00e1rio. O que a API oficial exige para enviar, quanto custa por mensagem e por que o grupo cabe 8.<\/p>\n","protected":false},"author":1,"featured_media":99,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-100","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-webhooks"],"_links":{"self":[{"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/posts\/100","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/comments?post=100"}],"version-history":[{"count":2,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/posts\/100\/revisions"}],"predecessor-version":[{"id":105,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/posts\/100\/revisions\/105"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/media\/99"}],"wp:attachment":[{"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/media?parent=100"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/categories?post=100"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/postping.com.br\/blog\/wp-json\/wp\/v2\/tags?post=100"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}