Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Como receber por webhook as mensagens de WhatsApp e os comentários nas redes sociais dos seus clientes

Cada ligação recebe o seu próprio webhook para as mensagens de WhatsApp ou os comentários nas redes sociais dos seus clientes, através da Partner API da easyCoexistence. As mensagens de WhatsApp seguem da Meta até esse endereço, assinadas com o segredo da aplicação Tech Provider e não com um que esteja na sua posse, pelo que um segredo longo e aleatório no caminho do endereço as autentica. Os comentários e DMs do Instagram e do Facebook, e os comentários do TikTok, são reencaminhados à medida que chegam, assinados por conta com X-EC-Signature.

200 characters

Tamanho máximo, segundo a Meta, do URL de callback alternativo que envia as mensagens de um número para o seu endpoint.

7 days

Período durante o qual a Meta volta a enviar um webhook do WhatsApp que o seu endpoint não aceitou, com frequência decrescente, o que pode gerar duplicados.

AS32934

A rede da Meta; as consultas whois de rotas listam os endereços de onde chegam os webhooks do WhatsApp, que a Meta altera periodicamente.

3 MB

O tamanho máximo de um payload de webhook do WhatsApp, segundo a Meta.

5 minutes

Idade a partir da qual o carimbo temporal assinado de um evento reencaminhado deve ser rejeitado, comparando o HMAC em tempo constante.

Como cada ligação obtém o seu próprio destino?

Através de uma chamada por recurso. Um número de WhatsApp recebe PUT /connections/{id}/webhook com um url e um verify_token, ou o mesmo par como webhook_url e webhook_verify_token na sua sessão de ligação, para que o número lhe seja encaminhado desde o primeiro minuto. Uma conta social recebe PUT /channels/{id}/webhook depois de ligada. Um url de null em qualquer dos casos desativa a entrega. Os dois caminhos diferem em quem entrega e na forma de autenticar:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Como faz chegar as mensagens de um número ao seu endpoint?

Indique um URL HTTPS cujo caminho contenha um segredo longo e aleatório, juntamente com um token de verificação: webhook_verify_token numa sessão de ligação, com 8 a 200 caracteres, ou verify_token no PUT. A Meta verifica logo o URL com um GET que traz hub.mode=subscribe, hub.verify_token e hub.challenge, e o seu endpoint tem de responder com o valor de hub.challenge quando o token corresponder. Se esta validação falhar, o PUT devolve 502 meta_rejected com a mensagem própria da Meta; numa sessão de ligação, o número fica ligado na mesma, e o last_error da sessão indica o motivo por que o URL não foi aplicado.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

Porque não se pode verificar a assinatura da Meta, e o que a substitui?

A Meta assina cada entrega com X-Hub-Signature-256, um HMAC-SHA256 do payload com o App Secret da aplicação que recebe. Para os números dos seus clientes, essa aplicação é a aplicação Tech Provider da easyCoexistence, cujo segredo nunca é partilhado, pelo que o cabeçalho não pode ser verificado do seu lado. A credencial passa a ser o segredo longo e aleatório no caminho do endereço: compare-o em tempo constante e recuse tudo o que não corresponda. Como segunda camada, coloque na lista de permissões as rotas registadas na AS32934 da Meta e atualize essa lista, já que a Meta altera periodicamente os seus endereços IP.

Que webhooks do WhatsApp chegam ao seu URL?

Os campos que um URL de callback alternativo da Meta pode transportar: messages, para o que os clientes enviam e o estado do que é enviado; smb_message_echoes, para o que a empresa envia a partir da app do WhatsApp Business; e o histórico da importação única e smb_app_state_sync. A Meta nunca envia para um URL de substituição os webhooks de modelos, nem webhooks de conta como account_update. Esses chegam ao callback da easyCoexistence, por isso a revisão de modelos é lida por consulta periódica, e uma recusa chega-lhe como evento de estado.

  • O destino é definido na conta do WhatsApp Business, pelo que dois números na mesma conta o partilham: encaminhe com base em value.metadata.phone_number_id.
  • Os ficheiros multimédia chegam como ID; obtenha o ficheiro da Meta com o token do cliente a partir da chamada de credenciais.
  • Os payloads podem chegar a 3 MB, pelo que deve aumentar qualquer limite de tamanho do corpo definido abaixo desse valor.

Que aspeto tem um evento social reencaminhado?

Um POST com Content-Type application/json e um cabeçalho X-EC-Signature, que transporta quatro chaves: platform; account_id, o ID do canal que a Partner API utiliza; external_id, o ID da conta na rede; e entry. Para o Instagram e o Facebook, entry é a entrada de webhook da Meta sem alterações, com changes para comentários e menções e messaging para as mensagens diretas. Para o TikTok contém o evento comment.update com o conteúdo analisado, e comment_id, video_id e parent_comment_id como strings, para que os IDs de 64 bits não sejam arredondados.

  • As contas do Instagram estão subscritas a comentários, mensagens e menções; as Páginas do Facebook a feed, mensagens e menções; o TikTok envia comment.update.
  • A easyCoexistence não recebe eventos de comentários do YouTube nem do LinkedIn: o PUT deles responde 400 not_supported, e os comentários são lidos através da API de cada rede com as credenciais.
  • Os reencaminhamentos não trazem os cabeçalhos X-EC-Event nem X-EC-Delivery, por isso elimine duplicados com base nos IDs da própria rede, como um ID de comentário ou um mid de mensagem.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

Como verificar o X-EC-Signature, passo a passo?

Com o signing_secret que PUT /channels/{id}/webhook devolveu, mostrado apenas uma vez e exclusivo dessa conta. O cabeçalho tem a forma t=<unix>,v1=<hex>. Depois, para cada entrega:

  • Leia o corpo bruto do pedido como bytes, antes de qualquer análise JSON.
  • Divida o cabeçalho por vírgulas em t, um tempo Unix em segundos, e v1, um digest hexadecimal.
  • Rejeite a entrega se t diferir mais de 5 minutos do seu relógio.
  • Calcule em hexadecimal o HMAC-SHA256 de t, um ponto e o corpo bruto, com o segredo dessa conta como chave.
  • Compare-o com v1 em tempo constante e, depois, responda com 2xx e ponha o trabalho em fila.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

O que acontece quando não há destino definido?

Nada chega, e nada fica à espera de ser enviado mais tarde. Um número sem webhook_url recorre ao callback da easyCoexistence, onde as suas mensagens são descartadas sem serem guardadas, e não recebe a importação do histórico de conversas, que só é pedida quando existe um destino. Uma conta social sem destino não é reencaminhada: os seus eventos continuam a chegar à aplicação da easyCoexistence, mas nenhum fica guardado para si. Defina cada destino antes de precisar do tráfego.

O que acontece a um destino quando uma ligação cai ou é removida?

Um número mantém o seu destino registado. Quando um número caído volta a ligar, a easyCoexistence define de novo o seu URL na Meta, e o mesmo acontece quando um número suspenso regressa. Remover uma conta social limpa o seu destino e o seu segredo, pelo que, depois de voltar a ligar, chame de novo PUT /channels/{id}/webhook e guarde o novo segredo. Esse PUT emite um novo segredo sempre que é chamado com um URL, e o antigo deixa de assinar de imediato.

Como configurar

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Erros comuns

  • Verificar o X-Hub-Signature-256 nas entregas de WhatsApp dos seus clientes. A Meta calcula-o com o App Secret da easyCoexistence, que nunca é partilhado, pelo que a verificação não pode passar; autentique com o segredo no caminho do endereço.
  • Verificar o X-EC-Signature sobre o JSON já analisado. O HMAC abrange o corpo bruto byte a byte, e voltar a serializá-lo altera os bytes, por isso verifique antes de analisar.
  • Usar um só segredo para todos os canais. Cada conta social assina com o seu próprio segredo, e os eventos de estado com outro, por isso procure o segredo pelo account_id.
  • Fazer trabalho lento antes de responder a um evento reencaminhado. Este é enviado uma vez, espera 8 segundos pela sua resposta e nunca é repetido, por isso responda primeiro com 2xx e processe depois.
Fazer isto com a EasyCoexistence

A easyCoexistence encaminha as mensagens de cada número de cliente da Meta até ao seu servidor, e os comentários e DMs do Instagram e do Facebook, bem como os comentários do TikTok, até ao seu endpoint à medida que chegam, assinados por conta, sem cópia guardada e com cada ligação monitorizada 24/7. De US$ 9 a US$ 0.75 por ligação e por mês, com preço decrescente à medida que adiciona ligações, com os primeiros 3 dias grátis.

Perguntas frequentes

Posso verificar a assinatura da Meta nas mensagens de WhatsApp dos seus clientes?

Não. A Meta assina-as com o segredo da aplicação Tech Provider da easyCoexistence, que nunca é partilhado. Autentique com o segredo longo e aleatório no caminho do URL e, opcionalmente, com os intervalos de IP da Meta.

As ligações ao YouTube e ao LinkedIn reencaminham eventos de comentários?

Não. A easyCoexistence não recebe eventos de comentários de nenhuma das duas, por isso PUT /channels/{id}/webhook responde 400 not_supported. Leia os comentários através da API de cada rede com as credenciais do canal.

Os eventos sociais reencaminhados são repetidos se o meu servidor estiver em baixo?

Não. Cada um é enviado uma vez e não fica nenhuma cópia guardada. As entregas do WhatsApp são diferentes, porque a própria Meta as volta a tentar durante até 7 dias.

As mensagens passam pela easyCoexistence?

No WhatsApp, não: a Meta entrega as mensagens de um número ao webhook que definiu. Os comentários e DMs das redes sociais são reencaminhados ao seu endpoint à medida que chegam, assinados por conta, sem cópia guardada.

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