Embedded Signup do WhatsApp: conecte à API em minutos

O Embedded Signup do WhatsApp é a janela da própria Meta que abre dentro do site de um parceiro para conectar o seu número à API oficial. Nela você entra com a conta que administra a empresa, escolhe o portfólio de negócios, a conta do WhatsApp Business e o número, e autoriza o parceiro a operar esse número. Ao final, a Meta entrega ao parceiro só os identificadores e um código de autorização; a sua senha nunca passa por ele. O processo inteiro leva minutos, e não exige criar um app no Meta for Developers nem ler documentação.

Este artigo explica o que acontece em cada tela, quem está do outro lado da janela, o que falta fazer depois de conectar e os erros que de fato acontecem no caminho.

O que é o Embedded Signup, em resposta curta

Antes do Embedded Signup, usar a API oficial do WhatsApp exigia criar um app de desenvolvedor na Meta, pedir permissões, passar por revisão e configurar tudo à mão. Era um trabalho de programador, e a maior parte das empresas contratava um intermediário para fazê-lo.

O Embedded Signup inverte isso. O parceiro, que já tem o app aprovado pela Meta, embute no site dele um botão que abre uma janela da Meta. A janela é hospedada pela Meta, roda no domínio dela e é ela quem autentica você. O parceiro só recebe o resultado: o número ficou vinculado ao app dele, e ele pode enviar e receber mensagens em seu nome.

Segundo a documentação da Meta, o fluxo cria ou associa três coisas: o portfólio de negócios, a conta do WhatsApp Business (WABA, na sigla em inglês) e o número. É por isso que ele serve tanto para quem já tem tudo cadastrado quanto para quem está começando do zero na Meta.

Nota: Embedded Signup é o nome técnico. Em português, alguns provedores chamam de "cadastro incorporado" ou só de "conectar pela Meta". É a mesma janela.

O que acontece na janela da Meta, passo a passo

A janela tem poucas telas, e vale saber o que cada uma pede para não travar no meio.

Portfólio de negócios, conta do WhatsApp Business e número

1. Login na Meta. Você entra com a conta pessoal do Facebook que administra a empresa. Se a empresa ainda não tem portfólio de negócios, a janela oferece criar um na hora.
2. Portfólio de negócios. É a entidade que representa a empresa na Meta, a mesma do Business Manager. O número e a conta do WhatsApp Business vão pertencer a ele, não ao parceiro.
3. Conta do WhatsApp Business. Você escolhe uma existente ou cria uma nova. Ela agrupa os números, os templates e o método de pagamento.
4. Número. Aqui os dois caminhos se separam: um número que já está no app WhatsApp Business do celular, ou um número novo que vai viver só na API. A próxima seção detalha a diferença.
5. Confirmação. No caminho do número que já está no app, o celular pede confirmação e pergunta se você quer compartilhar histórico e contatos com o parceiro. No caminho do número novo, a Meta envia um código de verificação por SMS ou ligação.

Ao concluir, a janela fecha e o site do parceiro recebe o resultado. Do lado do parceiro, ainda faltam algumas chamadas à Meta: trocar o código de autorização por um token, conferir o estado do número e assinar os eventos. Tudo isso acontece nos segundos seguintes, sem a sua participação.

O que a Meta devolve ao parceiro e o que ele não vê

O que sai da janela para o parceiro é pequeno e bem definido: o identificador da conta do WhatsApp Business, o identificador do número e um código de autorização de uso único, trocável por um token de acesso. O evento de conclusão tem esta forma:

{
  "type": "WA_EMBEDDED_SIGNUP",
  "event": "FINISH",
  "data": {
    "phone_number_id": "123456789012345",
    "waba_id": "987654321098765"
  }
}

O que o parceiro não recebe: a sua senha do Facebook, o acesso à sua conta pessoal, os outros ativos do portfólio (páginas, contas de anúncio, outros números). O token que ele obtém vale só para o que a janela autorizou, e pode ser revogado por você no Business Manager a qualquer momento, em Configurações, Parceiros.

Para que essa janela sequer abra, o app do parceiro precisa ter passado pelo App Review da Meta com acesso avançado a duas permissões, whatsapp_business_management e whatsapp_business_messaging. Um parceiro sem essa aprovação não consegue conectar cliente nenhum pelo Embedded Signup, o que já é um primeiro filtro de seriedade.

Dois caminhos: número que já está no app ou número novo

A escolha do número decide o que acontece depois. A tabela resume o que muda, e o artigo sobre coexistência do WhatsApp Business com a API aprofunda o primeiro caminho.

O detalhe do registro é o que torna os dois caminhos incompatíveis entre si. Um número novo precisa ser registrado por uma chamada da API, e sem ela nenhum envio funciona. Um número em coexistência já está registrado, pelo app do celular, e repetir o registro desloga o aplicativo, de forma irreversível daquele lado. Um parceiro que trate os dois caminhos do mesmo jeito derruba o WhatsApp do celular de quem escolheu coexistência.

Na prática, o parceiro informa à Meta qual caminho quer antes de abrir a janela, e a própria Meta filtra os números que aparecem para escolher. Se você pediu número novo e escolheu um que na verdade está no app, um parceiro cuidadoso corrige a modalidade para coexistência e segue, porque isso é seguro. O contrário, registrar por conta própria um número que a Meta diz não estar no app, nunca deve acontecer de forma automática.

Quem está do outro lado: Tech Provider x Solution Partner

O parceiro que abre a janela é sempre uma empresa cadastrada na Meta como provedor de soluções. A Meta reconhece dois tipos, e a diferença muda o que você paga e para quem.

Segundo a página da Meta sobre provedores, o Solution Partner é um Meta Business Partner que oferece o serviço completo: a mensageria, a integração, o suporte e o faturamento. É o único tipo que pode estender linha de crédito e cobrar o cliente pelo uso da API. O Tech Provider oferece o software, e só ele. A Meta cobra o cliente diretamente pelas mensagens, e o Tech Provider cobra apenas pelo próprio produto.

O que costuma se chamar de BSP, sigla de Business Solution Provider, é o nome antigo do Solution Partner. Não é sinônimo de Tech Provider, embora os dois abram a mesma janela.

Por que com um Tech Provider você paga a Meta direto

A consequência prática é a que mais importa para quem escolhe. Com um Tech Provider, o custo por mensagem é o da tabela da Meta, sem intermediário, e aparece na fatura do seu próprio Business Manager. O provedor não tem como colocar margem nas mensagens, porque o dinheiro não passa por ele. O que ele cobra é o software, em geral por número ou por assinatura.

Com um Solution Partner, a fatura da Meta vem embutida na fatura do parceiro, que pode oferecer crédito, pagamento em real e condições próprias. Para operações grandes isso pode ser uma vantagem; para a maioria das empresas, é uma camada a mais entre você e o preço publicado. O artigo sobre quanto custa a WhatsApp Business API separa o que é da Meta do que é do provedor.

O Frame Conexa é um Tech Provider verificado pela Meta, com o App Review aprovado em agosto de 2026. É isso que permite ao painel abrir o Embedded Signup e conectar números de clientes.

Como saber se o parceiro é verificado

Não existe um selo visível na janela, mas há três sinais que não dá para falsificar.

O primeiro é a própria janela: ela é da Meta, no domínio da Meta, e mostra o nome do app e da empresa que pede a autorização. Se o "provedor" pede a sua senha do Facebook num formulário do site dele, ou pede que você leia um QR code como no WhatsApp Web, isso não é Embedded Signup. É outra coisa, e o artigo sobre API oficial x não oficial explica o risco.

O segundo é o Business Manager. Depois de conectar, o parceiro aparece em Configurações, Parceiros, com os ativos a que tem acesso. Se ele não está lá, ele não está operando pela API oficial.

O terceiro é o teto de clientes. A Meta limita quantos clientes um app pode conectar: 10 por janela de 7 dias para app sem verificação, e 200 para quem completou a verificação da empresa, o App Review e a verificação de acesso. Um parceiro que conecta dezenas de clientes por semana só consegue isso porque passou pelas três.

Depois de conectar: pagamento na Meta e verificação da empresa

Conectar o número não termina o trabalho. Dois passos ficam do seu lado, e o parceiro não pode fazê-los por você.

Cadastrar o pagamento na Meta. Como o Tech Provider não estende crédito, a Meta exige que o dono da conta cadastre um método de pagamento no próprio Business Manager. Enquanto isso não acontece, a conta do WhatsApp Business fica bloqueada para envio fora da janela de atendimento: nenhuma mensagem aprovada pela Meta sai, nenhum envio em massa acontece. Responder a quem escreveu nas últimas 24 horas continua funcionando, o que engana: o atendimento parece saudável e a campanha não sai. O caminho é Business Manager, Configurações, Pagamentos, dentro do seu portfólio.

Vale saber que a cobrança da Meta muda em 01/10/2026: as mensagens de serviço, que são as respostas livres dentro da janela de 24 horas, e os templates de utilidade enviados dentro dessa janela passam a ser cobrados por mensagem. Até lá, essas mensagens são gratuitas. Consulte a tabela publicada pela Meta em setembro de 2026 e confira o rate card oficial antes de fazer conta.

Verificar a empresa. A verificação do portfólio no Business Manager, com documentos da empresa, é o que tira o número do primeiro degrau de capacidade. Sem ela, a conta começa com um limite de 250 destinatários únicos em 24 horas fora da janela de atendimento, e o crescimento depende do volume e da qualidade dos envios. O artigo sobre o limite de mensagens da WhatsApp Business API explica os degraus e a escalada automática.

Importante: os dois limites são da Meta, não do provedor. O bloqueio por falta de pagamento e o teto de capacidade aparecem no painel de qualquer parceiro, porque vêm da conta do WhatsApp Business, que é sua.

Erros reais do Embedded Signup e como resolver

O fluxo quase sempre termina bem. Quando não termina, o erro costuma ser um destes três, e todos foram medidos em conexões reais.

2388002: parceiro já atribuído à conta

Aparece na tela em que você informa o número, no caminho da coexistência, com a mensagem "Failed to check phone number eligibility". Nada chega ao parceiro, porque a autorização morre antes de ser emitida. De fora, parece que a pessoa fechou a janela.

A causa medida em produção, em agosto de 2026, foi um parceiro já atribuído: uma tentativa anterior do mesmo fluxo tinha deixado o parceiro com acesso à conta do WhatsApp Business daquele número. Com o parceiro lá, a checagem de elegibilidade falha em toda tentativa seguinte.

O conserto é no Business Manager do dono do número: Configurações, Parceiros, o parceiro em questão, a conta do WhatsApp, Gerenciar, Remover acesso. Ao refazer o fluxo, a elegibilidade passa e o próprio Embedded Signup reatribui o parceiro. Não remova o número da conta nem apague a conta do WhatsApp Business para "começar do zero": a elegibilidade para coexistência depende do histórico do número no app, e reiniciar esse vínculo zera o relógio.

Autorização concluída, mas nada aconteceu: a janela de 15 minutos

O SDK da Meta que abre a janela tem um prazo de 15 minutos, contado a partir do carregamento da página, não do clique. Se a pessoa leva mais que isso dentro da janela, confirmando no celular, lendo as telas, esperando o SMS, a autorização é concluída do lado da Meta, mas o site do parceiro já desistiu de esperar. Resultado: a janela fecha com aparência de sucesso e nada acontece.

Medimos isso em setembro de 2026, num cliente que perdeu duas autorizações seguidas por esse motivo antes de conectar na terceira. A lição é simples: abra a janela com o celular na mão, o app WhatsApp Business atualizado e aberto, e siga sem pausas. Se passou dos 15 minutos, recarregue a página e refaça. Nada foi quebrado na Meta; a autorização anterior só não foi recebida.

É também por isso que um parceiro cuidadoso registra cada queda do funil, com o motivo. Sem isso, "a Meta recusou", "a pessoa desistiu" e "passou do prazo" viram a mesma coisa no suporte.

Bloqueio de pop-up e navegador

A janela da Meta é um pop-up. Navegadores bloqueiam pop-ups que não nascem de um clique direto, e alguns bloqueiam todos por padrão. No Safari, em particular, qualquer demora entre o clique e a abertura faz a janela se desprender do site, e a autorização conclui na Meta sem que o site fique sabendo. Um parceiro bem implementado abre a janela na primeira instrução do clique, e pré-carrega o que precisa antes de habilitar o botão.

Do seu lado: permita pop-ups para o site do parceiro, use Chrome, Edge ou Firefox se o Safari estiver dando trabalho, e evite abrir o fluxo dentro do navegador embutido de outro app, como o do Instagram ou do WhatsApp, que não abre pop-ups de forma confiável.

Como é no Frame Conexa: painel, link compartilhável ou SDK

No Frame Conexa, o Embedded Signup aparece em três lugares, para três situações diferentes.

No painel. É o caminho de quem tem o celular na mão e a conta no painel. O botão Conectar WhatsApp abre um fluxo guiado de cinco passos, escolhe a modalidade antes de abrir a janela da Meta, confere o estado do número depois da autorização e, no caso da coexistência, acompanha a importação do histórico. Qualquer queda do funil, inclusive o 2388002 e o prazo de 15 minutos, fica registrada com o motivo.

Por link compartilhável. Nem sempre quem contrata é quem tem o WhatsApp. Uma agência, um consultor ou um software que atende vários clientes gera no painel um link de conexão e manda para o cliente final. Ele abre o link, sem login, e faz só a autorização na Meta. O número nasce na conta de quem gerou o link e usa a vaga dele. O link vale para um único uso e só é consumido no sucesso, para que um erro no meio não deixe o cliente trancado do lado de fora.

Pelo SDK, para parceiros. Um software que quer conectar os números dos próprios clientes de dentro do produto dele usa a API pública para gerar o link e um SDK em JavaScript para abrir a tela de conexão a partir de um botão próprio. A conexão abre em aba, não em pop-up, porque a janela da Meta precisa abrir por cima e um pop-up dentro de outro pop-up é recusado por ela.

Nos três casos, depois da conexão o número responde à API pública como qualquer outro. O primeiro envio é o do guia de início rápido:

curl -X POST https://frameconexa.com/api/v1/instances/$FRAME_CONEXA_INSTANCE_ID/messages \
  -H "Authorization: Bearer fc_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"5585999990000","type":"text","text":{"body":"Olá!"}}'

E as mensagens que chegam são entregues ao seu sistema por webhook assinado, como descrito em como integrar a WhatsApp Cloud API com webhook. Nada do que acontece depois depende de qual dos três caminhos abriu a janela.

Próximo passo

Se o número está pronto e o celular na mão, a conexão pelo painel leva os minutos que este artigo descreve. Veja os planos por número para escolher entre atendimento e marketing, e o guia de início rápido para o primeiro envio por código logo depois.