Webhooks da Meta para a plataforma do Messenger

Com os Webhooks, você pode receber notificações HTTP em tempo real sobre mudanças em objetos específicos no gráfico social da Meta. Por exemplo, é possível enviar uma notificação sempre que uma pessoa enviar uma mensagem para sua Página do Facebook ou conta profissional do Instagram. Essas notificações possibilitam monitorar mensagens recebidas e atualizações no status de mensagens. Elas também ajudam a evitar limites de volume que poderiam ocorrer se você consultasse os pontos de extremidade da plataforma do Messenger para rastrear essas alterações.

Para implementar Webhooks em conversas do Messenger ou do Instagram, você precisará fazer o seguinte:

1. Criar um ponto de extremidade no seu servidor para receber e processar as notificações do Webhooks (objetos JSON)
2. Configurar o produto Webhooks da Meta no Painel de Apps
3. Assinar as notificações que você quer receber do Webhooks da Meta
4. Instalar seu app de mensagens na Página do Facebook vinculada à sua empresa ou à sua conta profissional do Instagram

Pré-requisitos

Antes de começar:

• Leia e implemente os componentes necessários para desenvolver com a Meta na Visão geral da plataforma do Messenger.
• Publicar app da Meta
• Requisitos de acesso

  • O Acesso padrão para receber notificações de pessoas que têm uma função no seu app, como administradores, desenvolvedores ou testadores; ou
  • Advanced Access para receber notificações de clientes, ou seja, pessoas que não têm uma função no seu app. Requer a Análise do App.

Configurar o servidor Node.JS

Seu servidor deve processar dois tipos de solicitação HTTPS: solicitações de verificação e notificações de evento. Como as duas solicitações usam HTTPS, o servidor deve ter um certificado TLS ou SSL válido configurado e instalado corretamente. Os certificados autoatribuídos não são suportados.

As seções abaixo explicam o conteúdo de cada tipo de solicitação e como responder a elas.

Os exemplos de código foram retirados do nosso exemplo de app no GitHub. Visite o GitHub para ver o exemplo completo e as informações sobre a configuração do servidor de webhooks.

Criar um ponto de extremidade

Para criar um ponto de extremidade com objetivo de receber notificações de webhooks da plataforma do Messenger, o arquivo app.js poderá ter a seguinte aparência:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

Esse código cria um ponto de extremidade /webhook que aceita solicitações POST e verifica se a solicitação é uma notificação de webhook.

Retornar uma resposta 200 OK

O ponto de extremidade deve retornar uma resposta 200 OK, a qual informa à plataforma do Messenger que o evento foi recebido e não precisa ser reenviado. Normalmente, você só envia essa resposta após concluir o processamento da notificação.

Responder a notificações de eventos

Seu ponto de extremidade deve responder a todas as notificações:

• com uma resposta 200 OK HTTPS;
• em até 5 segundos.

O código estará em app.post no seu arquivo app.js e terá aparência semelhante a esta:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

Solicitações de verificação

Enviaremos uma solicitação GET para o URL do ponto de extremidade sempre que você configurar o produto Webhooks no Painel de Apps. As solicitações de verificação incluirão os seguintes parâmetros da string de consulta, anexados ao final do URL do ponto de extremidade. Elas serão assim:

Exemplo de solicitação de verificação

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

Como validar as solicitações de verificação

Sempre que seu ponto de extremidade receber uma solicitação de verificação, você deverá:

• verificar se o valor hub.verify_token corresponde à string definida no campo Verificar token quando você configura o produto Webhooks no Painel de Apps (você ainda não configurou essa string do token);
• responder com o valor hub.challenge.

Seu arquivo app.js terá aparência semelhante a esta:

// Add support for GET requests to your webhook
app.get("/webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

Observação: o PHP converte pontos (.) em sublinhados (_) nos nomes dos parâmetros.

Se você estiver no Painel de Apps e configurar o produto Webhooks (e isso acionará uma solicitação de verificação), o painel indicará se o ponto de extremidade validou a solicitação corretamente. Se você usar o ponto de extremidade /app/subscriptions da Graph API para configurar o produto Webhooks, a API responderá com sucesso ou falha.

Notificações de eventos

Na configuração do produto Webhooks, você assinará fields específicos em um tipo de object (por exemplo, o campo messages no objeto page). Sempre que houver uma mudança em um desses campos, enviaremos uma solicitação POST ao seu ponto de extremidade com uma carga JSON descrevendo a alteração.

Por exemplo, se você assinar o objeto page no campo message_reactions e um dos clientes reagir a uma mensagem enviada pelo seu app, enviaremos a você uma solicitação POST semelhante a esta:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

Conteúdo da carga

As cargas conterão um objeto descrevendo a mudança. Ao configurar o produto Webhooks, você pode indicar se as cargas devem conter somente os nomes dos campos alterados ou se elas devem incluir também os novos valores.

Como formatamos todas as cargas com JSON, é possível analisar a carga usando métodos ou pacotes comuns de análise de JSON.

Observação:: não será possível consultar dados de notificações referentes a eventos históricos de webhook. Por isso, capture e armazene o conteúdo de todas as cargas de webhook que você deseja manter.

Validar cargas

Assinamos todas as cargas de notificação de eventos com uma assinatura SHA256 e a incluímos no cabeçalho "X-Hub-Signature-256" da solicitação, precedida por "sha256=". A validação de carga não é obrigatória. No entanto, essa é uma prática recomendada.

Para validar a carga:

1. gere uma assinatura SHA256 usando a carga e a chave secreta do app;
2. compare sua assinatura com a do cabeçalho X-Hub-Signature-256 (tudo que aparece após sha256=). Se as assinaturas coincidirem, a carga será verdadeira.

O arquivo app.js terá aparência semelhante a esta:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Nova tentativa de entrega de webhooks

Caso o envio de uma notificação para seu servidor falhe, tentaremos mais algumas vezes. Seu servidor deverá lidar com a desduplicação nesses casos. Se ainda não conseguirmos entregar notificações depois de 15 minutos, um alerta será enviado para sua conta de desenvolvedor.

Caso a entrega de uma notificação siga falhando por uma hora, você receberá um alerta de desativação de webhooks. Além disso, seu app será removido dos webhooks da Página ou da conta profissional do Instagram. Quando você corrigir os problemas, será necessário assinar os Webhooks novamente.

Testar os Webhooks

Para testar a verificação do webhook, execute a seguinte solicitação de cURL com seu token de verificação:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Se a verificação do webhook estiver funcionando conforme o esperado, você verá o seguinte:

• O WEBHOOK_VERIFIED conectado à linha de comando onde o processo do nó está sendo executado.
• O CHALLENGE_ACCEPTED conectado à linha de comando de onde você enviou a solicitação de cURL.

Para testar o webhook, envie esta solicitação de cURL:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Se o webhook estiver funcionando conforme o esperado, você verá o seguinte:

• A TEST_MESSAGE conectada à linha de comando onde o processo do nó está sendo executado.
• O EVENT RECEIVED conectado à linha de comando de onde você enviou a solicitação de cURL.

Assinar Webhooks da Meta

Depois que o ponto de extremidade do servidor de webhooks ou o app de exemplo estiver pronto, acesse o Painel de Apps para assinar Webhooks da Meta.

Neste exemplo, usaremos o painel para configurar um webhook e assinar o campo messages. Sempre que um cliente enviar uma mensagem ao seu app, uma notificação será encaminhada ao ponto de extremidade de webhooks.

1. No Painel de Apps, navegue até Produtos > Messenger > Configurações.
   • Alguns webhooks da plataforma do Messenger não estão disponíveis para mensagens do Instagram. Se estiver apenas implementando webhooks para o Instagram e souber quais deles estão disponíveis para o recurso de mensagens, será possível assiná-los aqui. Para assinar webhooks somente de mensagens no Instagram, acesse as Configurações do Instagram.
2. Insira o URL do ponto de extremidade no campo URL de retorno de chamada e insira o token de verificação no campo Verificar token. Incluiremos essa string em todas as solicitações de verificação. Se você estiver usando um dos nossos apps de exemplo, deverá ser a mesma string usada para a variável de configuração TOKEN do app.
3. Escolha os campos que quer assinar e clique em Salvar.
4. A última etapa é assinar campos individuais. Assine o campo messages e envie uma notificação de evento de teste.
   • Se o ponto de extremidade for configurado corretamente, ele validará a carga e executará o código que você configurou caso a validação seja bem-sucedida. Se você usar o exemplo de app, carregue o URL do app no navegador da web. Ele deve exibir o conteúdo da carga.

É possível alterar as assinaturas, a verificação do token ou a versão da API a qualquer momento usando o Painel de Apps.

Observação: é recomendável usar a versão mais recente da API para receber todas as informações disponíveis para cada webhook.

Isso também pode ser feito de modo programático usando o ponto de extremidade /app/subscriptions.

Campos disponíveis da plataforma do Messenger

Conectar o app

É preciso conectar o app Webhooks à sua Página e assinar as notificações que você quer receber.

Adicionar o app

Conecte o app a uma Página em Meta Business Suite > Todas as ferramentas > Apps de negócio.

Observação: é preciso assinar os webhooks de mensagem para todos os apps de mensagem da empresa.

Assinar sua Página

É necessário assinar sua Página nas notificações do Webhooks que você quer receber.

Requisitos

• Um token de acesso à Página solicitado por uma pessoa que pode executar a tarefa MODERATE na Página que está sendo consultada.
• As permissões pages_messaging e pages_manage_metadata.

Para assinar um campo do Webhooks, envie uma solicitação POST para a borda subscribe_apps da Página usando o token de acesso da Página.

curl -i -X POST "https://graph.facebook.com/<PAGE_ID>/subscribed_apps
  ?subscribed_fields=messages
  &access_token=<PAGE_ACCESS_TOKEN>"

Exemplo de resposta

{
  "success": "true"
}

Para ver quais apps estão instalados na sua Página, envie uma solicitação GET:

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/<PAGE_ID>/subscribed_apps
  &access_token=<PAGE_ACCESS_TOKEN>"

Exemplo de resposta

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "<APP_ID>",
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Se a Página não tiver apps instalados, a API retornará um conjunto de dados vazio.

Explorador da Graph API

Você também pode usar o Explorador da Graph API ao enviar a solicitação de assinatura da sua Página a um campo do Webhooks.

1. Selecione o app no menu suspenso App.
2. Clique no menu suspenso Obter token e selecione a opção Obter token de acesso do usuário. Depois, escolha a permissão pages_manage_metadata. A ação substituirá o token do app por um token de acesso do usuário com a permissão pages_manage_metadata concedida.
3. Clique novamente em Obter token e selecione sua Página. A ação substituirá o token de acesso do usuário por um token de acesso à Página.
4. Altere o modo de operação clicando no menu suspenso GET e selecionando POST.
5. Substitua a consulta padrão me?fields=id,name pelo ID da Página seguido por /subscribed_apps. Depois, envie a consulta.

Próximas etapas

• Enviar uma mensagem de teste: saiba como usar a plataforma para enviar mensagens.
• Exemplo de app: baixe o código do nosso exemplo de app para saber mais sobre os recursos oferecidos pela plataforma do Messenger.

Veja também

• Saiba como receber notificações quando uma conversa é passada de um app para outro usando a API de Encaminhamento de Conversas
• Saiba mais sobre Webhooks da Meta para a Graph API