Webhooks Meta для платформы Messenger

Webhooks Meta позволяют в режиме реального времени получать уведомления HTTP об изменениях определенных объектов в социальном графе Meta. Например, вы можете получить уведомление, когда кто-либо отправляет сообщение вашей Странице Facebook или профессиональному аккаунту Instagram. Уведомления Webhooks позволяют отслеживать входящие сообщения и изменения статусов сообщений. Кроме того, уведомления Webhooks позволяют избегать ограничений числа обращений, которые могут налагаться, если вы отправляли к конечным точкам платформы Messenger запросы об отслеживании изменений.

Чтобы правильно внедрить Webhooks для переписок в Messenger или Instagram, вам необходимо:

1. Создать конечную точку на своем сервере для получения и обработки уведомлений Webhooks и объектов JSON.
2. Настроить продукт Meta Webhooks на панели своего приложения.
3. Подписаться на уведомления Meta Webhooks, которые вы хотите получать.
4. Установить свое приложение для переписок на Страницу Facebook, связанную с вашей компанией или бизнес-аккаунтом Instagram.

Прежде чем начать

Перед началом работы вам необходимо:

• рассмотреть и внедрить компоненты, необходимые для разработки с Meta (см. Обзор платформы Messenger).

Конфигурация вашего сервера Node.JS

Ваш сервер должен быть в состоянии обрабатывать два типа HTTPS-запросов: запросы подтверждения и уведомления о событиях. Так как оба типа запросов используют протокол HTTPS, на вашем сервере должен быть установлен и настроен действующий сертификат TLS или SSL. Самозаверенные сертификаты не поддерживаются.

В следующих разделах описаны запросы обоих типов и объясняется, как на них следует отвечать.

Используемые здесь примеры кодов взяты из нашего примера приложения, размещенного на GitHub . Перейдите на GitHub, чтобы ознакомиться с полным примером и получить дополнительную информацию о настройке вашего сервера Webhooks.

Создание конечной точки

Чтобы создать конечную точку для получения уведомлений Webhooks от платформы Messenger, файл app.js может выглядеть следующим образом:

// 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 });
    
...
   

Этот код создает конечную точку /webhook, которая принимает запросы POST и проверяет, являются ли они уведомлениями Webhooks.

Возврат ответа 200 OK

Эта конечная точка должна вернуть ответ 200 OK, по которому платформа Messenger узнает, что событие получено и отправлять его повторно не нужно. Как правило, этот ответ отправляется по завершении обработки уведомления.

Ответы на уведомления о событиях

Ваша конечная точка должна отвечать на все уведомления:

• с ответом 200 OK HTTPS;
• в течение пяти или менее секунд.

Следующий код будет указан в app.post в вашем файле app.js и может выглядеть примерно так:

...
  // 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);
  }
}); 

Запросы подтверждения

При настройке продукта Webhooks на панели приложений мы отправляем на URL вашей конечной точки запрос GET. Запросы подтверждения включают в себя URL вашей конечной точки со следующими параметрами строки запроса. Они будут выглядеть примерно так:

Пример запроса подтверждения

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

Обработка запросов подтверждения

Когда ваша конечная точка получает запрос подтверждения, она должна:

• проверить, совпадает ли значение hub.verify_token со строкой, которую вы задали в поле Подтвердить маркер на панели приложений при настройке продукта Webhooks (сейчас она не задана);
• Ответьте значением hub.challenge.

Ваш файл app.js может выглядеть примерно так:

// Add support for GET requests to our webhook
app.get("/messaging-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);
    }
  }
});

Примечание: PHP преобразует точки (.) в названиях параметров в знаки подчеркивания (_) .

Если вы настраиваете продукт Webhooks на панели приложений и инициируете таким образом запрос подтверждения, вы увидите на панели, правильно ли ваша конечная точка подтвердила запрос. Если вы настраиваете продукт Webhooks с помощью конечной точки /app/subscriptions API Graph, этот API отправит ответ об успешном или неудачном подтверждении.

Уведомления о событиях

При настройке продукта Webhooks вы подписываетесь на определенные поля (fields) типа object (например, на поле messages объекта page). При изменении одного из этих полей мы будем отправлять на вашу конечную точку запрос POST с полезными данными JSON, описывающими изменение.

Например, если вы подписались на принадлежащее объекту page поле message_reactions и кто-либо из клиентов отреагировал на сообщение, отправленное вашим приложением, мы отправим вам запрос POST, который будет иметь примерно такой вид:

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

          ...
        }
      ]
    }
  ]
}

Полезные данные

Полезные данные содержат объект, описывающий изменение. При настройке продукта Webhooks можно указать, должны ли полезные данные содержать только названия измененных полей или также и их новые значения.

Они всегда имеют формат JSON, поэтому их можно анализировать с помощью стандартных методов и пакетов для анализа JSON.

Проверка полезных данных

Мы подписываем полезные данные уведомлений о событии с использованием алгоритма SHA256 и добавляем эту подпись в заголовок 'X-Hub-Signature-256' запроса, добавляя перед ней 'sha256='. Вы не обязаны проверять полезные данные, но вам следует их подтвердить, и мы вам настоятельно рекомендуем это сделать.

Как проверить полезные данные:

1. Сгенерируйте подпись SHA256, используя полезные данные и секрет приложения.
2. Сравните свою подпись с подписью в заголовке X-Hub-Signature-256 (после sha256=). Если подписи совпадают, полезные данные подлинны.

Файл app.js может выглядеть примерно так:

// 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.");
    }
  }
}

Повторная попытка доставки Webhooks

Если отправка уведомления на ваш сервер не удастся, мы сразу же выполним несколько повторных попыток. В таких случаях ваш сервер должен выполнить дедупликацию. Если через 15 минут мы всё ещё не сможем доставить уведомления, на ваш аккаунт разработчика будет отправлено сообщение.

Если уведомление не удается отправить в течение часа, вы получите оповещение Webhooks отключены, а ваше приложение будет отписано от Webhooks для Страницы или профессионального аккаунта Instagram. Как только вы устраните проблемы, вам необходимо будет снова подписаться на Webhooks.

Протестируйте свой Webhooks

Чтобы провести проверку Webhooks, отправьте следующий запрос cURL со своим маркером проверки:

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

Если проверка Webhooks выполняется без ошибок, вы увидите следующее:

• в командной строке, где выполняется процесс, появится сообщение WEBHOOK_VERIFIED;
• в командной строке, где был отправлен запрос cURL, появится сообщение CHALLENGE_ACCEPTED.

Чтобы протестировать Webhooks, отправьте следующий запрос cURL:

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

Если Webhooks работает без ошибок, вы увидите следующее:

• в командной строке, где выполняется процесс, появится сообщение TEST_MESSAGE;
• в командной строке, где был отправлен запрос cURL, появится сообщение EVENT RECEIVED.

Подписка на Webhooks Meta

Когда ваша конечная точка сервера Webhooks или пример приложения будут готовы, перейдите в панель приложений и подпишитесь на Webhooks Meta.

В этом примере мы будем использовать панель для настройки Webhooks и подписки на поле messages. Каждый раз, когда клиент отправляет сообщение вашему приложению, на вашу конечную точку Webhooks будет отправляться уведомление.

1. На панели приложений перейдите в раздел Продукты > Messenger > Настройки.
   • Некоторые Webhooks платформы Messenger недоступны для переписок в Instagram. Если вы реализуете Webhooks только для Instagram и знаете Webhooks, доступные для переписок в Instagram, то можете подписаться на них здесь. Чтобы только посмотреть и подписаться на Webhooks для переписок в Instagram, можно перейти в настройки Instagram.

2. Введите URL конечной точки в поле URL обратного вызова и добавьте свой маркер подтверждения в поле Подтвердить маркер. Мы будем добавлять эту строку во все запросы подтверждения. Если вы используете один из наших примеров приложений, она должна совпадать со строкой, которую вы использовали в переменной TOKEN своего приложения.

3. Подпишитесь на поля, для которых вы хотите получать уведомления, и нажмите Сохранить.

4. Чтобы завершить процедуру, вам нужно подписаться на отдельные поля. Подпишитесь на поле messages и отправьте тестовое уведомление о событии.

   Если конечная точка настроена правильно, она должна подтвердить полезные данные и выполнить заданный код. Если вы используете наш пример приложения, загрузите URL приложения в браузере. Должны отобразиться полезные данные.

Вы можете в любой момент изменить свои подписки Webhooks, подтвердить маркер или версию API на Панели приложений.

Примечание. Рекомендуется использовать самую новую версию API, чтобы получать всю доступную информацию о каждом вызове Webhooks.

Это также можно сделать программным путем через конечную точку /app/subscriptions.

Доступные поля платформы Messenger

Подключение приложения

Вам необходимо подключить свое приложение Webhooks к своей Странице и подписать эту Страницу на уведомления Webhooks, которые вы хотите получать.

Добавление приложения

Вы можете подключить приложение к Странице в меню Meta Business Suite > Все инструменты > Объекты компании.

Примечание. На Webhooks сообщений необходимо подписать все приложения компании для обмена сообщениями.

Подписка Страницы

Вам необходимо подписать свою Страницу на уведомления Webhooks, которые вы хотите получать.

Требования

• Маркер доступа к Странице, запрошенный у пользователя, который может выполнять задачу MODERATE на этой Странице.
• Разрешенияpages_messaging и pages_manage_metadata.

Чтобы подписаться на поле Webhooks, отправьте запрос POST к границе контекста subscribed_apps Страницы с использованием маркера доступа Страницы.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

Пример ответа

{
  "success": "true"
}

Чтобы посмотреть, какие приложения установлены для вашей Страницы, отправьте вместо этого запрос GET:

Пример запроса

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Пример ответа

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

Если для Страницы не установлено ни одно приложение, API вернет пустой набор данных.

Graph API Explorer

Вы также можете отправить запрос и подписать свою Страницу на поле Webhooks с помощью Graph API Explorer .

1. Выберите свое приложение в раскрывающемся меню Приложение.
2. Раскройте меню Получить маркер и выберите Получить маркер доступа пользователя. Затем выберите разрешение pages_manage_metadata. Маркер приложения будет заменен маркером доступа пользователя с разрешением pages_manage_metadata.
3. Нажмите Получить маркер ещё раз и выберите свою Страницу. Маркер доступа пользователя будет заменен маркером доступа к Странице.
4. Измените метод: раскройте меню GET и выберите POST.
5. Подставьте в me?fields=id,name в запросе по умолчанию id Страницы, за которым следует код /subscribed_apps, а затем отправьте запрос.

Требования для доступа

Чтобы получать уведомления от пользователей, имеющих роль в вашем приложении (например, от администраторов, разработчиков или тестировщиков), приложению необходим только стандартный уровень доступа. Чтобы получать уведомления от клиентов (пользователей, у которых нет роли в приложении), потребуется расширенный доступ.

Подробнее о стандартном и расширенном доступе, данных, которые они предоставляют, и требованиях для реализации см. в этой статье .

Дальнейшие действия

Обзор примера приложения : скачайте код нашего примера приложения, чтобы узнать больше о функциях платформы Messenger.

Дополнительная информация

• Узнайте, как получать уведомления о переносе переписки из одного приложения в другое с помощью протокола передачи в Messenger
• Подробнее о Meta Webhooks для API Graph