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.
Throughput fixo de um número usado com a app do WhatsApp Business e a Cloud API.
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.
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.
A janela de serviço ao cliente do WhatsApp após uma mensagem ou chamada do utilizador; cada nova mensagem a repõe.
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:
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 aowebhook_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.
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.
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