AllService AI Estudos API de Conversões no WhatsApp
Fonte oficial · Meta for Developers e Central de Ajuda da Meta · ref. out/2026O clique tem um ID.
O lead, um evento.
A API de Conversões da Meta mede o lead do anúncio de clique para o WhatsApp quando a empresa envia o evento da conversa com o identificador do clique. Segundo a documentação lida pela AllService AI em 9 de outubro de 2026, a API aceita 14 tipos de evento de mensagem, entre eles lead qualificado e compra.
Publicado em 10 de outubro de 2026.
A API de Conversões no WhatsApp, em quatro números.
O que a documentação da Meta publica sobre os eventos, o identificador do clique, o prazo de envio e as permissões do app.
O anúncio de clique para o WhatsApp termina numa conversa. O que acontece nela, do cadastro à compra, entra no Gerenciador de Anúncios quando a empresa compartilha o evento com a Meta, e o caminho que a documentação descreve para isso é a API de Conversões para mensagens comerciais. Esta página lê a regra na fonte, com data: o que a API faz, quais eventos existem, que dados vão no evento, de onde sai o identificador do clique, o que precisa existir antes de ligar e onde a documentação para. Nenhum número daqui é de operação: são regras e números publicados pela Meta, com a data da leitura.
Os blocos: o que a API faz, eventos e dados, de onde vem o clique, o que precisa existir, quem qualifica o lead, perguntas frequentes, os limites, como citar e as fontes.
Fontes: Meta for Developers, Conversions API for Business Messaging, parâmetros da API de Conversões, changelog e referências de webhook da WhatsApp Business Platform, em inglês; Central de Ajuda da Meta para Empresas e blog do WhatsApp Business, em português; lidos em 9 de outubro de 2026.
O pixel fica no site. A conversa, não.
O que a documentação para desenvolvedores e a Central de Ajuda da Meta dizem de cada integração, na versão lida em 9 de outubro de 2026.
A documentação para desenvolvedores descreve a API de Conversões como a conexão entre os dados de marketing do anunciante (eventos do site, do app, de mensagens comerciais e conversões offline) e os sistemas da Meta que otimizam a segmentação dos anúncios, reduzem o custo por resultado e medem resultados. Para mensagens, a Central de Ajuda em português define: "Os eventos de mensagens em chats comerciais são as ações que as pessoas realizam ao se comunicar com sua empresa no Messenger, no Instagram ou no WhatsApp."
Na página da Central sobre conjuntos de dados, o pixel aparece como "Pixel da Meta (eventos do site)", e a API como "API de Conversões (eventos do site, do app e de mensagens)". No anúncio de clique para o WhatsApp, o destino é uma conversa no aplicativo, e não uma página do site. A documentação da API para mensagens comerciais pede que o evento de mensagem represente só o que acontece na conversa, e não conversões em outros canais, como o site; a conversão que acontece fora da conversa vai pelo produto da API de Conversões do canal onde ela aconteceu.
| Seis dos nove valores de action_source | Onde a conversão aconteceu, segundo a referência |
|---|---|
business_messaging | A partir de anúncio de clique para o Messenger, o Instagram ou o WhatsApp. |
chat | Por app de mensagens, SMS ou recurso de mensagem on-line. |
website | No site. |
phone_call | Por telefone. |
physical_store | Pessoalmente, na loja física. |
other | De um jeito que a lista não traz. |
Os outros três valores da lista são email, app e system_generated: conversão por e-mail, no app para celular e gerada automaticamente, como a renovação de uma assinatura com pagamento automático todo mês. A referência de parâmetros acrescenta que todas as origens permitem medição, criação de público personalizado e otimização de anúncios; para mensagens, o guia da API ressalva que a otimização de compra só existe no anúncio de clique para o Messenger e para o WhatsApp, não no Instagram, e as páginas da Central divergem nesse ponto, como registram os limites. Para o site, a Central de Ajuda recomenda os dois juntos: "Se você usa a API de Conversões para enviar eventos da web, recomendamos usar também o pixel para maximizar a eficácia dos eventos do site." O post do blog do WhatsApp Business em português, de 7 de novembro de 2023, resume a proposta da API para o anúncio de clique como mensurar "os resultados importantes da parte inferior do funil, além das conversas iniciadas".
Fontes: Meta for Developers, Conversions API, Conversions API for Business Messaging e Server Event Parameters, em inglês; Central de Ajuda da Meta para Empresas, Sobre a API de Conversões, Sobre os eventos de mensagens nos chats comerciais e Sobre conjuntos de dados no Gerenciador de Eventos da Meta, e blog do WhatsApp Business, em português; lidos em 9 de outubro de 2026.
14 eventos e um identificador.
A lista de eventos e os campos do evento de mensagem que a documentação da API de Conversões para mensagens comerciais publica.
Nas perguntas frequentes da documentação, a lista tem 14 tipos de evento para mensagens comerciais. Agrupados por esta página: lead, com LeadSubmitted e QualifiedLead; compra e carrinho, com Purchase, InitiateCheckout, AddToCart, CartAbandoned e ViewContent; pedido, com OrderCreated, OrderShipped, OrderDelivered, OrderCanceled e OrderReturned; e avaliação, com RatingProvided e ReviewProvided. A documentação traz só os nomes, sem definir cada um; a Central de Ajuda diz que "Os eventos padrão são ações com nomes predefinidos, como uma compra ou cadastro enviado."
| Campo do evento | O que a documentação mostra |
|---|---|
event_name | O nome do evento, um dos 14 da lista; o guia usa Purchase, e a página Automatic Events API traz um exemplo com LeadSubmitted. |
event_time | O horário do fato, em segundos Unix e no fuso GMT; pode ser até 7 dias anterior ao envio. |
action_source | business_messaging, a origem das conversões vindas de anúncio de clique para o Messenger, o Instagram ou o WhatsApp. |
messaging_channel | whatsapp, o canal da conversa. |
user_data | O identificador da conta do WhatsApp Business e o ctwa_clid, que a referência de parâmetros manda enviar sem hash. |
custom_data | Moeda e valor, no exemplo de compra da documentação. |
O evento vai ao endereço de eventos do conjunto de dados, com o token de acesso, e a chamada de exemplo traz ainda o campo partner_agent, com o nome do parceiro. Depois do envio, a documentação diz que o evento deve aparecer no Gerenciador de Eventos, no conjunto de dados que o recebeu. Um prazo e uma regra valem para o envio: a referência de parâmetros aceita evento até 7 dias depois do fato e, se um deles passar disso, devolve erro para a requisição inteira e não processa nenhum; a documentação para mensagens comerciais diz que a Meta não ajuda a deduplicar esses eventos e recomenda que o anunciante deduplique antes de enviar.
Fontes: Meta for Developers, Conversions API for Business Messaging (exemplo de evento e perguntas frequentes), Automatic Events API (exemplo com LeadSubmitted), Server Event Parameters e Customer Information Parameters, em inglês; Central de Ajuda da Meta, Sobre os eventos de mensagens nos chats comerciais, em português; lidos em 9 de outubro de 2026.
O clique chega com a mensagem do anúncio.
O caminho do identificador do clique na documentação da WhatsApp Business Platform, e a exceção do anúncio no Status.
- O que é
- A documentação descreve o
ctwa_clidcomo um identificador pessoal, único por clique, que a empresa recebe quando a pessoa que entra na conversa veio de um anúncio de clique para o WhatsApp. A referência de parâmetros o define como o identificador de clique gerado pela Meta para esses anúncios. - Onde chega
- No objeto referral do webhook de mensagens, que só vem quando a mensagem foi enviada por um anúncio de clique para o WhatsApp, ao lado do identificador do anúncio, do link, do título e do texto do anúncio.
- O que fazer
- Guardar o identificador com a conversa e, quando a conversão acontecer dentro dela, enviá-lo à Meta pela API de Conversões, segundo a documentação. O campo vai sem hash, e a documentação o trata como obrigatório no evento.
- No Status
- O changelog registra, em 20 de outubro de 2025, que a mensagem de texto que nasce de um anúncio no Status do WhatsApp chega sem o identificador do clique. A referência do webhook de mensagens de texto e a dos eventos automáticos dizem que o campo é omitido por inteiro nesse caso.
| Data | O que a documentação registra | Onde |
|---|---|---|
| 27/09/2023 | O campo ctwa_clid entra no objeto referral do webhook de mensagens da API do WhatsApp (Cloud API). | Changelog da WhatsApp Business Platform |
| 07/11/2023 | O blog do WhatsApp Business publica em português que a API de Conversões está disponível para mensagens comerciais. | Blog do WhatsApp Business |
| 05/06/2025 | O Embedded Signup passa a oferecer a identificação automática de eventos de compra e de lead nas conversas de anúncio de clique para o WhatsApp. | Changelog |
| 08/10/2025 | A versão 4 do Embedded Signup inclui a API de Conversões entre os produtos do cadastro de clientes. | Changelog |
| 20/10/2025 | O changelog registra que a mensagem de texto que vem do anúncio no Status não traz o identificador do clique. | Changelog |
| 23/10/2025 | Data que a página da API de Conversões para mensagens comerciais ainda dá para a expiração da última versão do cliente On-Premises, que ela segue listando como opção; a recomendada é a API do WhatsApp (Cloud API). | Conversions API for Business Messaging |
Como o anúncio no Status funciona e quem pode comprar está em anúncio no Status do WhatsApp. Para a medição, o ponto é este: a documentação da API de Conversões trata o identificador como campo obrigatório do evento, e a conversa que vem do Status chega sem ele. Na Central de Ajuda, a página sobre como criar anúncios no Status diz que "os posicionamentos Advantage+ são selecionados por padrão, o que inclui automaticamente o Status do WhatsApp". Na leitura da AllService AI, quem roda com posicionamentos Advantage+, que incluem o Status por padrão, ou liga o Status à mão numa campanha medida por evento fica com uma parte das conversas sem o campo que liga o evento ao clique. A documentação lida não diz como a Meta trata essas conversas na medição.
Fontes: Meta for Developers, Conversions API for Business Messaging, Customer Information Parameters, changelog da WhatsApp Business Platform, Text messages webhook reference e automatic_events webhook reference, em inglês; blog do WhatsApp Business e Central de Ajuda da Meta, Como criar anúncios no Status do WhatsApp no Gerenciador de Anúncios da Meta, em português; lidos em 9 de outubro de 2026.
App, permissões, conta e conjunto de dados.
O que a documentação pede para o anúncio de clique para o WhatsApp, item por item, e os dois caminhos que a Central de Ajuda descreve.
| O que precisa existir | O que a documentação diz |
|---|---|
| App de desenvolvedor da Meta | Um app no painel de desenvolvedores; a documentação manda criar um, se a empresa ainda não tiver. |
| Duas permissões com acesso avançado | whatsapp_business_management e whatsapp_business_manage_events; quem já tem acesso avançado a whatsapp_business_messaging deve ter a segunda aprovada automaticamente depois de pedir. |
| Nível de acesso à API de Marketing | O recurso Marketing API Access Tier. Para o acesso completo, o corpo da página pede 1.500 chamadas bem-sucedidas nos últimos 15 dias, com taxa de erro abaixo de 10%; o aviso no topo diz que o patamar caiu para 500 chamadas. |
| WhatsApp Business Platform | A API do WhatsApp (Cloud API), que a documentação recomenda, ou a On-Premises a partir da versão 2.45.1. A página ainda lista a On-Premises, com a expiração da última versão do cliente marcada para 23 de outubro de 2025, quase um ano antes desta leitura. |
| Login e token de acesso | Embedded Signup ou Facebook Login for Business; o token precisa das duas permissões; a documentação recomenda reaproveitar o gerado no Embedded Signup e aceita token de usuário do sistema de integração comercial, de usuário do sistema ou de usuário que as contenha. |
| Conjunto de dados | Criado pela Dataset API com o identificador da conta do WhatsApp Business; se a conta já tiver um, a chamada devolve o existente. O conjunto é do cliente, e o parceiro acessa com as permissões necessárias. |
A documentação para desenvolvedores é escrita para o parceiro de mensagens comerciais que faz a integração em nome dos clientes. A Central de Ajuda descreve dois caminhos para compartilhar eventos de mensagens: a integração de um parceiro, em que "o parceiro pode compartilhar eventos de mensagens com a Meta em seu nome", e a integração direta, documentada no Meta for Developers. Nas perguntas frequentes da documentação, um conjunto de dados que já existe pode ser reaproveitado, só um conjunto de dados se vincula a uma Página do Facebook, e acrescentar mensagens a uma integração da API de Conversões que já envia eventos do site não traz risco, porque a atribuição se baseia no identificador da Página ou do conjunto de dados, e não no do app.
A identificação automática de eventos tem requisitos próprios: Embedded Signup já implementado, servidor de webhook processando as notificações e o app assinando o campo automatic_events. A documentação diz que a Meta usa expressões regulares e processamento de linguagem natural nas conversas novas de anúncio de clique para o WhatsApp e, quando conclui que houve um evento de lead ou de compra, dispara o webhook; enviar esse evento pela API de Conversões é opcional. O recurso não está disponível para empresas da União Europeia, do Reino Unido e do Japão.
Fontes: Meta for Developers, Conversions API for Business Messaging e Automatic Events API, em inglês; Central de Ajuda da Meta, Sobre os eventos de mensagens nos chats comerciais, em português; lidos em 9 de outubro de 2026.
O que a documentação deixa para quem qualifica.
O que a documentação diz e, em coluna própria, a leitura da AllService AI para quem qualifica o lead do anúncio na conversa.
| Ponto | O que a documentação diz | Leitura da AllService AI |
|---|---|---|
| Lead qualificado | QualifiedLead está na lista de eventos aceitos, sem definição do que conta como lead qualificado. | A régua é do negócio: o evento só existe se alguém, ou um sistema, marcar que aquela conversa qualificou. |
| Identificador do clique | Guardar o ctwa_clid com a conversa e enviá-lo quando a conversão acontecer. | A marcação precisa ficar presa à conversa que trouxe o identificador, desde a mensagem do anúncio. |
| Prazo | O evento pode ser enviado até 7 dias depois do fato; um evento mais antigo derruba a requisição inteira. | Qualificação marcada no dia em que acontece cabe no prazo; marcação deixada para o fim do mês pode não caber. |
Sobre otimização, as fontes não dizem a mesma coisa: a página da Central sobre eventos de mensagens fala em otimizar "para esses eventos", com compra como único exemplo; o guia da API para mensagens comerciais só nomeia compra; e a página Sobre a API de Conversões restringe a otimização a compra no Messenger. Nenhuma página nomeia lead ou lead qualificado como meta de otimização. Na leitura da AllService AI, a pergunta que decide vem antes da integração: em que momento, e por qual critério, a conversa passa a contar como lead qualificado. O que conta como lead qualificado, com as três peças (critério nomeado, pergunta que confirma e resposta registrada), está em qualificação de leads; como calcular a taxa de cada etapa sem errar o denominador, em taxa de conversão de leads.
| Ponto | O que a documentação diz | Leitura da AllService AI |
|---|---|---|
| Evento automático | A Meta identifica lead ou compra nas conversas de anúncio por expressões regulares e linguagem natural, para quem aderir. | A identificação automática diz que houve um cadastro na conversa; a documentação não diz que ela aplica a régua do negócio. |
| Duplicidade | A Meta não ajuda a deduplicar eventos de mensagens; a recomendação é deduplicar antes de enviar. | O lead que volta à mesma conversa precisa de registro para não virar um segundo evento de lead qualificado. |
| Dados sensíveis | A Central de Ajuda pede para não compartilhar dados sensíveis de usuários ao configurar os eventos. | Nos exemplos da documentação, o evento não leva o relato do caso; em serviço regulado, como a advocacia, o relato fica na conversa. |
Na triagem que a AllService AI descreve em página pública, a IA "lê o relato inteiro, inclusive o áudio transcrito, e marca o estado pela régua do escritório: qualificado ou desqualificado, com o motivo padronizado" (CRM para advogados). A página da casa descreve essa marcação e o painel que recebe o estado, e não fala em envio de evento à Meta. É esse tipo de marcação que a leitura acima pressupõe, venha ela de uma pessoa, de um CRM ou de uma triagem automatizada. O que decide se o lead chega a ser marcado, a velocidade da primeira resposta e a pergunta que separa, está em o que acontece depois do clique.
Fontes: Meta for Developers, Conversions API for Business Messaging, Server Event Parameters e Automatic Events API, em inglês; Central de Ajuda da Meta, Sobre os eventos de mensagens nos chats comerciais, em português; AllService AI, CRM para advogados; lidos em 9 de outubro de 2026.
Sobre a API de Conversões no WhatsApp.
As perguntas que mais aparecem, respondidas com a regra desta página.
O que é a API de Conversões da Meta para o WhatsApp?
É a integração que leva à Meta, do servidor da empresa ou de um parceiro, os eventos que acontecem na conversa aberta por um anúncio de clique para o WhatsApp, como lead qualificado e compra. Segundo a documentação lida pela AllService AI em 9 de outubro de 2026, cada evento volta com o identificador do clique, o ctwa_clid, e deve aparecer no Gerenciador de Eventos do conjunto de dados.
API de Conversões ou pixel da Meta: qual mede o lead do WhatsApp?
Para o que acontece na conversa, a API de Conversões. Na Central de Ajuda da Meta, o pixel aparece com os eventos do site e a API com os eventos do site, do app e de mensagens, e a documentação para desenvolvedores define a origem business_messaging como a conversão vinda de anúncio de clique para o Messenger, o Instagram ou o WhatsApp. Para eventos do site, a Central recomenda usar o pixel junto da API.
Como configurar a API de Conversões no WhatsApp?
Por um parceiro, que compartilha os eventos em nome da empresa, ou por integração direta. Na integração direta, a documentação pede, entre outros itens, um app da Meta com acesso avançado às permissões whatsapp_business_management e whatsapp_business_manage_events, integração com a WhatsApp Business Platform, de preferência pela API do WhatsApp (Cloud API), um token de acesso com essas permissões, o identificador da conta do WhatsApp Business e um conjunto de dados ligado a ela. Depois, cada evento vai ao conjunto de dados com o ctwa_clid da conversa.
Quais eventos de lead a API de Conversões aceita no WhatsApp?
A documentação lista 14 tipos de evento para mensagens comerciais, e os de lead são LeadSubmitted e QualifiedLead, ao lado de compra, carrinho, pedido e avaliação. A lista traz só os nomes, sem definir cada um, e a documentação pede que o evento de mensagem represente só o que acontece na conversa, e não conversões em outros canais, como o site.
Dá para otimizar a campanha de WhatsApp pelo lead qualificado?
Nenhuma página da Meta lida em 9 de outubro de 2026 nomeia lead ou lead qualificado como meta de otimização. A página da Central de Ajuda sobre eventos de mensagens fala em otimizar "para esses eventos", com compra como único exemplo; o guia da API para mensagens comerciais só nomeia compra, nos anúncios de clique para o Messenger e para o WhatsApp; e a página Sobre a API de Conversões restringe a otimização a compra no Messenger. O evento de lead qualificado está na lista de eventos aceitos, e a Central diz que os eventos de mensagens entram nos relatórios do Gerenciador de Anúncios.
O anúncio no Status do WhatsApp manda o identificador do clique?
Não. O changelog da WhatsApp Business Platform registra, em 20 de outubro de 2025, que a mensagem de texto que nasce do anúncio no Status chega sem o ctwa_clid, e a referência do webhook diz que o campo é omitido por inteiro. Como a documentação da API de Conversões trata o identificador como campo obrigatório do evento, na leitura da AllService AI essas conversas ficam sem o campo que liga o evento ao clique, o que vale para quem roda com posicionamentos Advantage+, que incluem o Status por padrão, ou liga o Status à mão.
O que esta página não prova.
Sete limites declarados, para nenhuma regra ser lida além do que diz.
Regra de plataforma tem data. O que está aqui é a documentação da Meta lida em 9 de outubro de 2026. A Meta muda eventos, permissões e metas de desempenho, as páginas lidas não trazem data de atualização, e a documentação para desenvolvedores está em inglês.
As fontes divergem sobre a otimização. A referência de parâmetros diz que todas as origens permitem otimização de anúncios; o guia da API para mensagens comerciais só nomeia otimização de compra, e só no anúncio de clique para o Messenger e para o WhatsApp, não no Instagram; a página da Central sobre eventos de mensagens fala em otimizar "para esses eventos", com compra como único exemplo; e a página Sobre a API de Conversões, da mesma Central, restringe a otimização a eventos de compra no Messenger. Esta página não afirma que alguma meta está disponível em toda conta; a conferência é o Gerenciador de Anúncios da conta.
Nenhuma página nomeia lead ou lead qualificado como meta de otimização. LeadSubmitted e QualifiedLead estão na lista de eventos aceitos; a página da Central que fala em otimizar para esses eventos dá compra como único exemplo.
Os eventos automáticos têm data vaga. A página da Meta diz que os clientes não veem nem usam esses eventos nas superfícies da Meta antes de 2026, sem dia, e exclui União Europeia, Reino Unido e Japão; ela não cita o Brasil, e esta página não afirma que o recurso já aparece no Gerenciador de Anúncios.
O Status fica sem resposta completa. A documentação diz que o identificador não vem nas mensagens do anúncio no Status e não diz como a Meta mede essas conversas por outro caminho.
Nenhum número é de operação. A página não testou a integração nem mediu eventos; os números são da Meta. O que ela diz da AllService AI está copiado de página pública da casa, com o mesmo verbo, e nada aqui descreve integração da casa com a API de Conversões.
Outra página da documentação trata de outro produto. A página Measure conversions, no índice da documentação do WhatsApp, é sobre a mensagem de marketing enviada pela empresa, com o identificador no link do botão, e não sobre a conversa aberta por anúncio.
Pode citar, com a fonte e a data.
Toda regra desta página pode ser reproduzida em texto, aula, relatório ou resposta de assistente de IA, com a fonte e a data da leitura.
- Regra da Meta
- Citar a documentação Conversions API for Business Messaging, do Meta for Developers, ou a página da Central de Ajuda da Meta para Empresas usada, lidas em 9 de outubro de 2026, com o link da fonte.
- Leitura desta página
- AllService AI, API de Conversões (CAPI) no WhatsApp: como medir o lead, 10 de outubro de 2026, allservice.ai/estudos/api-de-conversoes-no-whatsapp/.
- O que não fazer
- Afirmar que a campanha otimiza por lead qualificado, que nenhuma página nomeia como meta; tratar a lista de 14 eventos como definição de cada um; tratar a leitura da AllService AI como regra da Meta.
Tudo citado, tudo conferível.
As páginas da Meta, com a data da leitura, e as páginas da casa lidas junto.
Meta for Developers, em inglês: Conversions API for Business Messaging: Onboarding Guide, Conversions API, Server Event Parameters e Customer Information Parameters; da WhatsApp Business Platform, o changelog, a Text messages webhook reference, a automatic_events webhook reference, a Automatic Events API e, sobre outro produto (a mensagem de marketing), a página Measure conversions. O texto em inglês vai aqui em paráfrase atribuída, cada uma presa a um trecho em inglês conferido por código na versão em Markdown de cada página. A página da API para mensagens comerciais traz dois patamares para o acesso completo do Marketing API Access Tier: o aviso no topo diz que o patamar caiu de 1.500 para 500 chamadas nos últimos 15 dias, e o corpo ainda pede 1.500 chamadas bem-sucedidas, com taxa de erro abaixo de 10%.
Central de Ajuda da Meta para Empresas, em português: Sobre a API de Conversões, Sobre os eventos de mensagens nos chats comerciais do Messenger, Instagram ou WhatsApp, Sobre conjuntos de dados no Gerenciador de Eventos da Meta e Como criar anúncios no Status do WhatsApp no Gerenciador de Anúncios da Meta. WhatsApp Business, em português: Revolucionando as mensagens da empresa com a API de Conversões, post de 7 de novembro de 2023. Tudo lido em 9 de outubro de 2026.
Na casa: a triagem descrita em CRM para advogados; o anúncio no Status, em anúncio no Status do WhatsApp; o que a resposta pela API do WhatsApp custa por mensagem, em WhatsApp cobrado por mensagem; a IA da Meta para o WhatsApp, em Meta Business Agent.
Em que momento a conversa vira lead qualificado?
Trinta minutos para olhar como o seu WhatsApp responde o lead que chega do anúncio, a qualquer hora, e onde a qualificação entra na conversa.