EntrarComeçar teste grátis
easyCoexistence APIs oficiais

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.

20 mps

Throughput fixo de um número usado com o app do WhatsApp Business e com a Cloud API.

2.24.17

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.

180 days

Até onde vai o histórico de conversas que a Meta pode compartilhar na integração; ele precisa ser sincronizado em até 24 horas.

24 hours

A janela de atendimento do WhatsApp após uma mensagem ou chamada do usuário; cada nova mensagem a reinicia.

October 15, 2026

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:

1ConnectEmbedded Signup with Coexistence on a hosted page
2Routewebhook_url set on the number as it connects
3ReceiveMeta posts messages and echoes to your server
4ReplyCloud API calls with the customer's token
5WatchStatus events when the number drops or returns

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 seu webhook_url.
  • Mídia: POST /<PHONE_NUMBER_ID>/media para fazer upload; mídias recebidas chegam como um ID para buscar com o mesmo token.
Reply inside the customer service window
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.
Fazendo isso com o EasyCoexistence

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