POST graph.user.subscribe

Подписка на получение сообщений о событиях в чатах на webhook / с помощью long polling

Внимание! POST-запросы должны выполняться с заголовком Content-Type: application/json;charset=utf-8

При подписке на все Webhook из списка подписанных приходят сообщения о событиях в чате.

В качестве сообщений выступают данные о следующих событиях: * изменение состояния чата (изменение названия, иконки чата); * новое сообщение в чате (только сообщения, написанные не владельцем чата, который подписан на Webhook); * действия над участниками чата (добавление нового участника, выход участника из чата)

Сообщения в чате могут содержать приложения (изображение, видео, аудиозапись, share ссылки), это также отображается в сообщении, приходящем на Webhook.

https://api.ok.ru/graph/me/subscribe
   ?access_token=tkn18YdUJZe:CQABPOJKAKEKEKEKE

Пример POST-payload

Доступны два вида подписок:

  • webhook-подписка. Сообщения будут приходить на указанный при подписке URL;
  • long polling-подписка. Сообщения получаются вами с помощью метода GET graph.user.updates

Webhook-подписка

Смотри

{
  "url": String  /* http: или https: URL, куда будут доставляться сообщения о событиях в чатах */
}

Long polling-подписка

{
  "types": ["MESSAGE_CREATED|MESSAGE_CALLBACK|CHAT_SYSTEM"], /* типы сообщений, который можно получить с помощью подписки */
  "longPolling": true
}

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

  • MESSAGE_CREATED - создание нового сообщения;
  • MESSAGE_CALLBACK - нажатие на callback-кнопку;
  • CHAT_SYSTEM - системное сообщение. Например, старт чата с группой пользователем при переходе по особой ссылке.

Обработка запроса от API

На зарегистрированные Webhook URL’ы будут отправляться уведомления о входящих сообщениях методом POST в формате JSON.

На каждый такой запрос скрипт должен в течение максимум 5 секунд вернуть HTTP ответ со статусом 200 OK. Если отправка уведомления не удалась, или если скрипт вернул ответ со статусом, отличным от 200, через некоторое время будет предпринята попытка повторной отправки уведомления. Если в течение 8 часов от скрипта не было получено положительного ответа, регистрация указанного Webhook может быть автоматически отменена.

Запросы могут производиться только с определенного списка IP-адресов:

  • 217.20.145.192/28
  • 217.20.151.160/28
  • 217.20.153.48/28

Ответ

{
  "success": true       /* Индикатор того, что подписка произошла успешно */
}

Примеры сообщений

При появлении нового события в чате / диалоге на зарегистрированный Webhook приходит сообщение с информацией об этом событии.

Сообщения аналогичны тем, которые можно получить при вызове метода /me/messages.

Новое сообщение (без приложения):

{
  "webhookType" : "MESSAGE_CREATED",
  "sender": {
    "user_id": "user:123456789012"
  },
  "recipient": {
    "chat_id": "chat:C3ecb9d02a600"
  },
  "message": {
    "text": "text",
    "seq": 98211023614189660,
    "mid": "mid:C3ecb9d02a600.15cea67d78d2059"
  },
  "timestamp": 1498581292941
}

Новое сообщение (с приложением):

{
  "webhookType" : "MESSAGE_CREATED",
  "sender": {
    "user_id": "user:123456789012"
  },
  "recipient": {
    "chat_id": "chat:C3ecb9d02a600"
  },
  "message": {
    "text": "https://ya.ru/",
    "seq": 98211018056672380,
    "attachments": [
      {
        "type": "SHARE",
        "payload": {
          "url": "https://ya.ru/"
        }
      }
    ],
    "mid": "mid:C3ecb9d02a600.15cea668c4c2481"
  },
  "timestamp": 1498581208140
}

Системное сообщение (открытие чата по спец. ссылке):

{
  "webhookType" : "CHAT_SYSTEM",
  "type": "CHAT_STARTED",
  "sender": {
    "user_id": "user:123456789012"
  },
  "recipient": {
    "chat_id": "chat:C3ecb9d02a600"
  },
  "payload": "payloadText"
  "timestamp": 1498581208140,
}
  • Пример спец. ссылки:
https://ok.ru/%7BgroupName%7D/messages/start/%7BcustomText%7D%20

или

https://ok.ru/group/%7BgroupId%7D/messages/start/%7BcustomText%7D%20