Как настроить Webhook на уведомления messengers?

Что такое Webhook?  

Для общения двух систем, в нашем случае это может быть Ваш messengers бот и Chat API, нам необходимо настроить их взаимодействие таким образом, чтобы информация об изменениях статуса в одной, была доступна для другой. Например, отслеживание изменений статуса сообщений - отправлено, доставлено и прочитано.

Работая через API у Вас есть возможность отправлять GET и POST запросы для отслеживания изменений, но подобный подход не слишком удобен, поскольку Вам будет необходимо отправлять запросы с постоянной периодичностью, что все равно не исключает рисков узнать об изменениях статуса слишком поздно. Поэтому и существует вебхук, настроив который Вы будете получать уведомления на события. В зависимости от настройки Вы будете получать уведомления о сообщениях, об их статусах, о статусе инстанса и даже о пропущенных звонках. Вебхук вызывается когда происходит событие, поэтому вам не требуется отправлять запросы каждый раз, чтобы узнать, например, о новых сообщениях или статус вашего подключенного телефона. Эти уведомления придут автоматически как только произойдет это событие.

Вам необходимо разместить свой вебхук скрипт на хостинге и указать URL адрес в личном кабинете. Указать можно как URL адрес так и IP.

Примеры реализации Webhook

• Пример создания messengers бота на Java.
• messengers бот с API Google Таблиц на NodeJS.
• Создание messengers бота на C#.
• Создание messengers бота на Node.js.
• Создание messengers бота на Python. 
• Создание бота messengers на PHP.

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

Для подключения messengers API Вам могут помочь эти материалы.

Сейчас Chat API предлагает самое доступное и автоматизированное на рынке подключение к messengers Business API с моментальным доступом, вместе с визуальным конструктором чат ботов, который не требует знания кода, и с чат платформой.

messengers Business API – это самый надежный способ познакомить более чем 2 миллиардную аудиторию мессенджера с вашим бизнесом или продуктом. Подключайтесь к Chat API.

Спасибо, что посетили наш сайт. Наша команда желает Вам успеха во всех делах!

Эти туториалы содержат варианты реализации Webhook скрипта на разных языках программирования, Вы можете ими воспользоваться в качестве примеров при запуске своего Webhook сервера. Как указать и тестировать Webhook адрес с помощью инструментов Chat API, а также более тонких моментов настройки Webhook мы расскажем ниже.

Как мне протестировать работу Webhook?
Чтобы проверить и протестировать работу Webhook и убедиться, что сервер отправляет данные, мы предлагаем Вам два варианта:

1. Встроенные инструменты тестирования личного кабинета ChatAPI
Для этого перейдите в раздел тестирования в личном кабинете.  Для проверки Webhook нам будут интересны два раздела – это «Симуляция Webhook» и «Проверка Webhook».

Симуляция Webhook
Этот инструмент позволяет симулировать Post запрос на указанный Вами адрес Webhook.

Адрес устанавливается в основном меню выбранного инстанса.

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

Для симуляции Post запроса необходимо иметь оплаченный инстанс. Выбрать необходимый можно в верхней части окна. Симулятор может отправить три вида запроса – «Получено новое сообщение», «Доставлено», «Прочитано». На каждый случай будет формироваться свое отдельное ACK-уведомление.

Для отправки запроса просто выберите инстанс, установите адрес и нажмите кнопку отправить. Ответ придет незамедлительно. Если по каким-то причинам данные не пришли, то скорее всего в связке «Сервер – Endpoint» возникли сложности. Для того, чтобы проверить на чьей стороне возникли неполадки и отладить работу с Webhook, мы предлагаем воспользоваться разделом «Проверка Webhook».

Проверка Webhook

Проверка Webhook – это раздел, где Вы можете ознакомиться со входящими запросами от сервера - непосредственно с теми данными, которые будут приходить на Ваш http или https URL адрес. Обратите внимание! При работе с данным инструментом автоматически будет подставляться наш RequestBin Webhook адрес. После завершения тестирования, он сменится на указанный ранее.

С помощью «Проверки Webhook» Вы сможете ознакомиться с данными, которые будут приходить к Вам от сервера, а также убедиться, что запросы отправляются корректно. Используйте для отправки запросов «Симулятор Webhook» или же «Отправку сообщений» в разделе тестирования. Так будет выглядеть входящее сообщение :

а так уведомление, что сообщение было доставлено:

2. Webhook.Site
Есть несколько бесплатных ресурсов, которые берут на себя возможность приема и обработки данных и с которых можно взять url адрес для работы с Webhook. Для тестирования Вы можете воспользоваться подобным сайтом – мы рекомендуем Webhook.Site поскольку часто с ним работали и оставались довольны.  

Принцип работы остается примерно таким же. Скопируйте url и вставьте адрес в личном кабинете. Сохраните. После чего можно приступать к отправке сообщений и от сервера на сайт будет поступать информация.

Важные примечания!
При отправке сообщений с телефона вручную, на эти сообщения не будут формироваться ACK статусы уведомления – «Отправлено», «Доставлено», «Прочитано». Используйте для отправки сообщений раздел «Отправка сообщений» в инструментах тестирования.

Обратите внимание, что ответ «Sent-True» означает, что запрос был обработан, а не тот факт, что сообщение дошло до получателя. Вполне возможно, что пользователь не получил сообщение, определить это наверняка возможно через ACK статус уведомления.

Вот так выглядит само сообщение в Webhook. Site

АСК статус «Отправлено»

АСК статус «Доставлено»

АСК статус «Прочитано»   

А также статус инстанса

Как мне настроить Webhook? Каким требованиям он должен соответствовать?
Мы в меньшей степени может помочь с настройкой Вашего Webhook сервера, обратитесь к инструкциям по созданию ботов, которые мы указывали выше.  Самым Важным критерием для нас является ответ 200-го статуса. Если наш сервер получает этот ответ, то значит все было сделано верно.

Какую информацию передает сервер?
Количество данных отправляемых сервисом достаточно объёмно. Разберем основные параметры. 
Отправленное сообщение

ID – идентификатор конкретного сообщения.
BODY – основное содержание сообщения. Здесь может быть  текст, файл, ссылка или оповещение, например -  «Call-Miss».
FROMME – «True» - Вы отправили сообщение. «False» - входящие.
SELF – показывает откуда было отправлено сообщение. «0» - сообщение отправлено с телефона, «1» - сообщение было отправлено с API.
ISFORWARDED – пересланное сообщение. «0» - нет, «true» -пересылаемое сообщение.  
AUTHOR – автор сообщения.
TIME – время по UNIX. Чтобы его расшифровать можно воспользоваться специальными конвертерами.
CHATID – идентификатор конкретного диалога.
MESSAGENUMBER – порядковый номер сообщения.
TYPE – характеристика, указывающая на форму сообщения. Это может быть текст "Chat" или "File".
SENDERNAME – имя отправителя. Указывается имя из телефонной книги пользователя, если имя не указано, то это будет номер.
CAPTION – подпись, как правило приписывается к фотографиям.
QUOTED - параметр приложений к пересылаемым сообщениям.
ACK – демонстрируется ACK статус, который был на момент обработки сообщения. 1 – sent, 2 – delivered, 3 – viewed. 
CHATNAME – имя чата, которое прописал пользователь в messengers.
INSTANCEID – номер инстанса.

Отправленное сообщение

Обратите внимание, что параметр ACK отсутствует, поскольку на входящие не формируются ACK статус уведомления.

Статус Инстанса

authenticated - Авторизация пройдена успешно

подстатусы:
- normal - держите телефон подключенным;
- phone - телефон не подключен;
- computer - попытка подключения к телефону
- offline - компьютер не подключен
- battery_low - низкий заряд батареи телефона
- syncing - идет синхронизация;

init - Это начальный статус. Включение
loading - Загрузка, повторите через 30 секунд.

Дополнительные настройки Webhook
Существует ряд настроек, которые влияют на объём данных пересылаемых сервером, эти настройки можно изменять через документацию или частично через основное меню инстанса. Разберем эти параметры поближе.

 1 – statusNotificationsOn – включает или выключает сбор данных об изменениях статуса или подстатуса инстанса. Параметр используется для отслеживания состояния инстанса. Например, если возникли неполадки с подключением, сервер отправит данные и Вы оперативно об этом узнаете.
2 – ackNotificationsOn – включает доставку ACK уведомлений о статусе сообщения. Отправлено, доставлено и прочитано. С этим данными Вы можете выстраивать работу логики бота и отслеживать показатели эффективности рассылки сообщений.
3 – chatUpdateOn – изменение состояний чатов.
4 - videoUploadOn - включить или выключить автозагрузку видео из сообщений. Эта информация станет отображаться во входящих данных от сервера.
5 – guaranteedHooks – в стандартном варианте работы сервером производится одна попытка для получения 200-го статуса. Если что-то идет не так, например, messengers на телефоне уходит в фоновой режим, то хук не будет доставлен. Включив данный параметр, сервер будет добиваться отправки хука, производя до 20 попыток.
6 – parallelHooks – если Вы работаете с большим количеством входящих хуков, то они могут формировать очередь на доставку. Чтобы получать все хуки сразу можно воспользоваться данным параметром. При этом, обратите внимание, что включение данной функции увеличит нагрузку на Ваш скрипт обработки входящих Post запросов от сервера.
Ознакомиться со всей документацией Chat API  можно здесь.

Также, мы рекомендуем посмотреть видео гайд, где мы настраиваем Webhook уведомления: