Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Como adicionar WhatsApp ao seu SaaS com Embedded Signup e Coexistence

Um SaaS adiciona WhatsApp ao ligar o número existente de cada cliente através do Embedded Signup da Meta com Coexistence, para que o número continue a funcionar na app do WhatsApp Business. Com a Partner API da easyCoexistence, uma sessão de ligação por cliente executa este fluxo numa página alojada, a Meta entrega as mensagens do número ao seu webhook_url, e o seu backend responde pela Cloud API com o token próprio do cliente.

20 mps

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

2.24.17

A versão mais antiga da app do WhatsApp Business com que o número de um cliente se pode ligar através da Coexistence.

180 days

Até quanto tempo atrás recua o histórico de conversas que a Meta pode partilhar na integração; tem de ser sincronizado em 24 horas.

24 hours

A janela de serviço ao cliente do WhatsApp após uma mensagem ou chamada do utilizador; cada nova mensagem a repõe.

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 o WhatsApp?

São cinco, e a easyCoexistence assume a primeira e a última. O seu produto mantém a lógica da conversa, a caixa de entrada e tudo o que o seu modelo ou a equipa dos seus clientes escreve, 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 é que a Coexistence muda para os seus clientes?

Mantêm o número e o telemóvel. A app do WhatsApp Business continua a funcionar ao lado da Cloud API, pelo que a equipa responde no telemóvel enquanto o seu produto responde pela API, e o que enviam a partir da app chega ao seu webhook como smb_message_echoes. Vêm com três limites: o número envia a um ritmo fixo de 20 mensagens por segundo, só a API pode enviar templates, e a Meta desliga o número quando o telemóvel fica inativo durante cerca de 14 dias.

Como é o passo de ligação no seu produto?

Um botão Connect WhatsApp chama POST /connect-sessions a partir do seu backend com um redirect_url, o id do cliente como external_ref, e webhook_url com webhook_verify_token, para que a Meta encaminhe o número para si desde o primeiro minuto. O cliente confirma uma lista de verificação curta na página alojada, executa o popup da Meta, lê um código QR com a app do WhatsApp Business e regressa a si com um connection_id. Se prefere executar o Embedded Signup a partir da sua própria app de Tech Provider, o guia do Embedded Signup explica como pesar essa opção.

Como chegam as mensagens ao seu backend?

Da Meta, diretamente para o webhook_url, sem passar pela easyCoexistence e sem cópia guardada. O campo messages transporta o que os clientes enviam e o estado do que envia, e smb_message_echoes transporta o que a equipa envia a partir da app. A Meta assina cada entrega com o app secret da easyCoexistence, que nunca é partilhado, por isso um segredo longo e aleatório no caminho da URL autentica-a. Dois números numa mesma WhatsApp Business Account partilham um destino: encaminhe com base em value.metadata.phone_number_id.

Como é que 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 devolve o send_endpoint. O texto livre é enviado dentro de 24 horas após a última mensagem da pessoa; depois disso, só 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, o nome do template e o seu código de idioma.
  • Criar um template: POST /<WABA_ID>/message_templates, depois consulte o estado, já que os resultados da revisão não chegam ao webhook_url.
  • Multimédia: POST /<PHONE_NUMBER_ID>/media para carregar; o conteúdo multimédia recebido chega como um ID que se obtém 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." }
  }'

O seu produto pode importar as conversas existentes do cliente?

Uma vez, na ligação. Com um webhook_url definido na sessão, a easyCoexistence pede à Meta que envie os contactos do número e, se o cliente aceitar na app, até 180 dias de conversas, que chegam como webhooks smb_app_state_sync e history. A Meta só o permite nas 24 horas seguintes à ligação, por isso tenha o endpoint a responder antes de o link ser enviado. O guia do histórico de conversas descreve os payloads.

Quem paga a Meta pelas mensagens?

O seu cliente. A Meta fatura as mensagens que o seu backend envia pela API à WhatsApp Business Account do próprio cliente, com um método de pagamento que ele adiciona aí, e uma empresa sem nenhum não pode enviar templates de marketing. A easyCoexistence cobra à sua conta por número ligado e nunca cobra mensagens nem aplica margem sobre os preços da Meta.

O que acontece quando um número cai?

A sua URL de eventos recebe connection.disconnected com o motivo da Meta quando é conhecido. PRIMARY_INACTIVITY é a regra dos 14 dias, e uma nova sessão de ligação para esse cliente traz de volta o mesmo número. connection.token_missing significa que o número foi ligado sem o token do cliente, por isso recebe mensagens mas não as pode enviar até que uma nova sessão o volte a ligar.

Erros comuns

  • Enviar o link de ligação antes de o endpoint do webhook responder. A importação do histórico corre uma só vez, nas 24 horas após a ligação, e o conteúdo enviado antes de a sua URL funcionar perde-se.
  • Responder com texto livre depois de fechar a janela. Passadas 24 horas desde a última mensagem da pessoa, só é entregue um template aprovado.
  • Disparar uma campanha a partir de um número à velocidade máxima. Um número em Coexistence envia a 20 mensagens por segundo, por isso coloque em fila os envios de cada número a essa taxa.
  • Esperar que a equipa envie templates a partir do telemóvel. Em Coexistence só a API os envia, por isso coloque os envios de templates no seu produto.
Fazer isto com a EasyCoexistence

A easyCoexistence adiciona WhatsApp ao seu SaaS com o Embedded Signup e a Coexistence da Meta, numa página alojada que mostra o seu nome: os clientes mantêm o número e a app do WhatsApp Business, a Meta entrega as mensagens ao seu servidor e os eventos assinados chegam-lhe. A mesma API liga Instagram, Facebook, TikTok, YouTube, LinkedIn e mais canais. De US$ 9 a US$ 0,75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

Um cliente pode ligar um número que está noutro fornecedor de API do WhatsApp?

Não, enquanto lá estiver. A lista de verificação da página alojada pede um número sem outro fornecedor de API nem ferramenta de automatização, por isso o cliente desliga-o primeiro desse fornecedor.

O meu SaaS pode enviar templates do WhatsApp para os seus clientes?

Sim, pela Cloud API com o token de cada cliente: crie o template na WhatsApp Business Account do cliente, aguarde a revisão da Meta e envie-o depois.

A easyCoexistence lê as mensagens de WhatsApp dos meus clientes?

Não. A Meta entrega as mensagens de um número diretamente para o webhook_url que definir. Um número sem webhook_url recorre ao callback da easyCoexistence, onde as mensagens são descartadas sem serem guardadas.

Quanto custa a easyCoexistence por número de WhatsApp?

De US$ 9 a US$ 0,75 por número por mês, conforme o escalão do total das suas ligações, com os primeiros 3 dias gratuitos. As cobranças de mensagens da Meta vão para a WhatsApp Business Account de cada cliente.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em