Руководство по быстрому началу работы

Если вы этого еще не сделали, следуйте руководству по настройке приложения, чтобы подготовить приложение Facebook к использованию с платформой Messenger.

Все запросы к API Messenger Platform авторизуются посредством включения маркера доступа на уровне страницы в параметре access_token строки запроса.

Создайте маркер доступа к Странице, если вы еще не сделали этого при настройке приложения Facebook. Для этого выполните следующие действия:

Маркер доступа к Странице и другую конфиденциальную информацию не рекомендуется жестко задавать в коде Webhook.

Для этого добавьте следующий код в переменные среды, где <PAGE_ACCESS_TOKEN> — это созданный маркер доступа, а <VERIFY_TOKEN> — случайная строка, которую вы задаете для проверки своего Webhook:

PAGE_ACCESS_TOKEN="

Теперь все, что вам необходимо сделать, это добавить маркер доступа к Странице и маркер подтверждения в Webhook в верхней части файла app.js, чтобы использовать его в логике Webhook:

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

Сначала мы смоделируем три функции, которые обработают входящие события Webhook и отправят ответ через API Send. Для этого добавьте в свой файл app.js следующее:

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

Чтобы отвечать людям в Messenger, необходимо понять, кто ваш собеседник. Для этого бот Messenger извлекает ID отправителя сообщения, действующего в пределах Страницы (PSID), из входящего события Webhook.

Что такое PSID?

Когда кто-то начинает переписку со Страницей Facebook, этому человеку присваивается уникальный ID, действующий в пределах Страницы (PSID). Этот PSID используется для идентификации человека при отправке сообщений.

Если вы настроили один из параметров в приведенном выше разделе Базовый проект у вас должна быть базовая конечная точка /webhook, которая принимает запросы POST и регистрирует основной текст событий Webhook, выглядящий следующим образом:

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

Если вам нужно узнать PSID отправителя, добавьте в блок body.entry.forEach следующий код, чтобы извлечь PSID из свойства sender.id события:

Мы хотим, чтобы наш бот мог обрабатывать два типа событий Webhook: messages и messaging_postback. Название типа не указано в событии, но мы можем узнать его из определенных свойств объекта.

Что такое события Webhook?

Платформа Messenger отправляет события Webhook, чтобы сообщить вам о действиях, которые происходят в Messenger. События отправляются в формате JSON в виде запросов POST к вашему Webhook. Подробнее см. в разделе События Webhook.

Для этого добавьте в блок body.entry.forEach своего Webhook условие, которое проверяет, содержит ли полученное событие свойство message или postback. Кроме того, мы добавим вызовы к функциям handleMessage() и handlePostback(), которые мы смоделировали ранее:

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Теперь, когда наши входящие сообщения направляются к соответствующей функции обработчика, мы настроим handleMessage(), чтобы обрабатывать и отвечать на обычные текстовые сообщения. Для этого измените код таким образом, чтобы он считывал полезные данные нашего ответа, а затем отправлял их к callSendAPI(). В ответ нам необходимо отправить обычное текстовое сообщение, поэтому мы присваиваем объекту JSON свойство "text":

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Теперь можно отправить первое сообщение с помощью API Send платформы Messenger!

В handleMessage() мы выполняем вызов к callSendAPI(), поэтому нам нужно обновить его, чтобы создать полноценный запрос и отправить его платформе Messenger. Запрос к API Send имеет два свойства:

• recipient: указывает адресата сообщения. В этом случае мы определяем человека по его PSID.
• message: указывает сведения об отправляемом сообщении. Здесь мы указываем содержимое сообщения, переданного от функции handleMessage().

Чтобы создать запрос, измените модель для callSendAPI() следующим образом:

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Теперь, чтобы отправить сообщение, нам остается лишь выполнить запрос POST к API Send в https://graph.facebook.com/v2.6/me/messages.

Обратите внимание: вам необходимо добавить PAGE_ACCESS_TOKEN в параметре access_token строки запроса URL.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Выполните тест!

Отправьте своей Странице Facebook еще одно сообщение в Messenger. Вы должны получить автоматизированный ответ от своего бота Messenger, который продублирует ваше сообщение и попросит отправить изображение.

Поскольку в ответ мы попросили получателя отправить изображение, далее нам необходимо обновить код для обработки вложения. Платформа Messenger автоматически сохраняет отправленные уведомления и предоставляет к ним доступ через URL в свойстве payload.url каждого указателя в массиве attachments, поэтому нам также необходимо извлечь эти данные из события.

Какие типы вложений поддерживаются?

Бот Messenger может отправлять и получать большинство типов объектов, в том числе изображения, аудио, видео и файлы. В переписке можно просмотреть и даже воспроизвести медиафайлы, что обеспечивает информативное общение.

Чтобы определить, является ли сообщение вложением, измените условие в функции handleMessage() для проверки received_message на свойство attachments, а затем извлеките URL. На практике мы бы выполнили массив, чтобы просмотреть все вложения, но в рамках этого руководства мы запросим только первое из них.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

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

Есть ли другие шаблоны сообщений?

Да! Платформа Messenger предлагает целый ряд полезных шаблонов, каждый из которых предназначен для разных структур сообщений, среди которых списки, квитанции, кнопки и т. д. Подробнее см. в разделе Шаблоны.

Шаблоны можно задать в свойстве attachment сообщения, которое содержит свойства type и payload. В payload мы можем задать параметры общего шаблона со следующими свойствами:

• template_type: задает тип шаблона, используемого для сообщения. Мы используем общий шаблон, поэтому здесь указано значение "generic".
• elements: задает индивидуально настроенные свойства шаблона. Для общего шаблона мы укажем заголовок, подзаголовок, изображение и две кнопки обратной передачи.

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

Последний шаг — обработка события Webhook messaging_postbacks, которое будет отправлено, когда получатель коснется одной из кнопок обратной передачи в нашем общем шаблоне.

Для чего нужны кнопки обратной передачи?

Кнопка обратной передачи отправляет вашему Webhook событие Webhook messaging_postbacks, которое включает в себя индивидуально настроенную строку из не более чем 1000 символов в свойстве payload. Благодаря этому вы можете без труда интегрировать разные полезные данные обратной передачи, в ответ на которые вы сможете определенным образом отреагировать.

Поскольку в ответ на общий шаблон получатель может коснуться одной из двух кнопок обратной передачи, мы отреагируем в соответствии со значением свойства payload в событии обратной передачи. Для этого измените handlePostback() следующим образом: