Como adicionar WhatsApp ao seu SaaS com Embedded Signup e Coexistência
Um SaaS adiciona WhatsApp conectando o número existente de cada cliente pelo Embedded Signup da Meta com Coexistência, para que o número continue funcionando no app do WhatsApp Business. Com a Partner API do easyCoexistence, uma sessão de conexão por cliente executa esse fluxo em uma página hospedada, a Meta entrega as mensagens do número ao seu webhook_url, e o seu backend responde pela Cloud API com o token do próprio cliente.
Throughput fixo de um número usado com o app do WhatsApp Business e com a Cloud API.
A versão mais antiga do app do WhatsApp Business com a qual o número de um cliente pode se conectar pela Coexistência.
Até onde vai o histórico de conversas que a Meta pode compartilhar na integração; ele precisa ser sincronizado em até 24 horas.
A janela de atendimento do WhatsApp após uma mensagem ou chamada do usuário; cada nova mensagem a reinicia.
A data em que a Meta descontinuou o Embedded Signup v2 e v3, com as integrações migradas para a v4.
Quais são as partes de uma integração com WhatsApp?
Cinco, e o easyCoexistence assume a primeira e a última. Seu produto mantém a lógica da conversa, a caixa de entrada e o que o seu modelo ou a equipe dos seus clientes escrever, enquanto a Meta transporta as mensagens entre o número e o seu servidor:
O que a Coexistência muda para os seus clientes?
Eles mantêm o número e o celular. O app do WhatsApp Business continua funcionando ao lado da Cloud API: a equipe responde pelo celular enquanto o seu produto responde pela API, e o que ela envia pelo app chega ao seu webhook como smb_message_echoes. Três limites acompanham isso: o número envia em uma taxa fixa de 20 mensagens por segundo, só a API pode enviar templates, e a Meta desconecta o número quando o celular fica inativo por cerca de 14 dias.
Como é a etapa de conexão no seu produto?
Um botão Connect WhatsApp que chama POST /connect-sessions a partir do seu backend, com um redirect_url, o id do seu cliente como external_ref, e webhook_url com webhook_verify_token, para que a Meta direcione o número para você desde o primeiro minuto. O cliente confirma uma lista curta de verificação na página hospedada, executa o pop-up da Meta, escaneia um QR code com o app do WhatsApp Business e retorna a você com um connection_id. Se vale executar o Embedded Signup pelo seu próprio app de Tech Provider, isso é avaliado no guia do Embedded Signup.
Como as mensagens chegam ao seu backend?
Da Meta, direto para o webhook_url, sem passar pelo easyCoexistence e sem cópia guardada. O campo messages traz o que os clientes enviam e o status do que você envia, e smb_message_echoes traz o que a equipe envia pelo app. A Meta assina cada entrega com o app secret do easyCoexistence, que nunca é compartilhado, então um segredo longo e aleatório no caminho da URL autentica a entrega. Dois números em uma mesma WhatsApp Business Account compartilham um destino: roteie por value.metadata.phone_number_id.
Como o seu backend responde e envia templates?
Com a Graph API da Meta e o token do cliente obtido em GET /connections/{id}?credentials=1, que também retorna o send_endpoint. Texto livre é enviado em até 24 horas da última mensagem da pessoa; depois disso, apenas um template que a Meta tenha aprovado:
- Resposta: POST /<
PHONE_NUMBER_ID>/messages com type text, dentro da janela. - Template: a mesma chamada com type template, um nome de template e o seu código de idioma.
- Criar um template: POST /<
WABA_ID>/message_templates, depois consulte o status, já que os resultados da análise não chegam ao seuwebhook_url. - Mídia: POST /<
PHONE_NUMBER_ID>/media para fazer upload; mídias recebidas chegam como um ID para buscar com o mesmo token.
curl -X POST "$SEND_ENDPOINT" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511987654321",
"type": "text",
"text": { "body": "Your table for 4 is booked for 8 pm." }
}'Seu produto pode importar os chats existentes do cliente?
Uma única vez, na conexão. Com um webhook_url definido na sessão, o easyCoexistence pede à Meta que envie os contatos do número e, se o cliente concordar no app, até 180 dias de chats, que chegam como webhooks smb_app_state_sync e webhooks de histórico. A Meta permite isso somente em até 24 horas após a conexão, então deixe o endpoint respondendo antes de enviar o link. O guia de histórico de chats descreve os payloads.
Quem paga a Meta pelas mensagens?
O seu cliente. A Meta cobra as mensagens que o seu backend envia pela API na WhatsApp Business Account do próprio cliente, com um método de pagamento que ele adiciona lá, e uma empresa sem nenhum não pode enviar templates de marketing. O easyCoexistence cobra da sua conta por número conectado e nunca cobra por mensagens nem aplica margem sobre os preços da Meta.
O que acontece quando um número cai?
Sua URL de eventos recebe connection.disconnected com o motivo da Meta, quando ele é conhecido. PRIMARY_INACTIVITY é a regra dos 14 dias, e uma nova sessão de conexão para aquele cliente traz o mesmo número de volta. connection.token_missing significa que o número se conectou sem o token do cliente, então ele recebe mensagens, mas não consegue enviar até que uma nova sessão o reconecte.
Erros comuns
- Enviar o link de conexão antes que o seu endpoint de webhook responda. A importação do histórico roda uma única vez, em até 24 horas da conexão, e o conteúdo enviado antes de a sua URL funcionar se perde.
- Responder com texto livre depois que a janela fecha. Passadas 24 horas desde a última mensagem da pessoa, só um template aprovado é entregue.
- Disparar uma campanha a partir de um número em velocidade máxima. Um número em Coexistência envia a 20 mensagens por segundo, então enfileire os envios de cada número nessa taxa.
- Esperar que a equipe envie templates pelo celular. Na Coexistência só a API os envia, então coloque os envios de template no seu produto.
O easyCoexistence adiciona WhatsApp ao seu SaaS com o Embedded Signup da Meta e a Coexistência, em uma página hospedada com o seu nome: seus clientes mantêm o número e o app do WhatsApp Business, a Meta entrega as mensagens ao seu servidor e os eventos chegam assinados. A mesma API conecta Instagram, Facebook, TikTok, YouTube, LinkedIn e mais canais que estão chegando. De US$ 9 a US$ 0.75 por conexão por mês, com o preço caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Um cliente pode conectar um número que está em outro provedor de API do WhatsApp?
Não enquanto ele estiver lá. A lista de verificação hospedada pede um número sem outro provedor de API ou ferramenta de automação, então o cliente o desconecta desse provedor antes.
Meu SaaS pode enviar templates de WhatsApp para os seus clientes?
Sim, pela Cloud API com o token de cada cliente: crie o template na WhatsApp Business Account dele, aguarde a análise da Meta e depois envie.
O easyCoexistence lê as mensagens de WhatsApp dos meus clientes?
Não. A Meta entrega as mensagens de um número direto para o webhook_url que você definir. Um número sem webhook_url cai no callback do easyCoexistence, onde as mensagens são descartadas sem serem armazenadas.
Quanto custa o easyCoexistence por número de WhatsApp?
De US$ 9 a US$ 0.75 por número por mês, conforme a faixa do total das suas conexões, com os primeiros 3 dias grátis. As cobranças de mensagens da Meta vão para a WhatsApp Business Account de cada cliente.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em