Сообщения от группы игры

Платформа Одноклассников позвляет реализовать общение между игрой и её игроками с помощью сообщений в чате между группой игры и пользователями.

Это позволит вам как оповещать пользователей о каких-либо событиях в игре наиболее эффективным способом, производя массовые рассылки и/или отправляя сообщения конкретным пользователям, так и просто поддерживать диалог с вашей аудиторией.

Как подключить

Для реализации сообщений от группы игры пользователям требуется выполнить следующие шаги:

запросить право BOT_API_INIT для вашей игры;
включить поддержку сообщений от группы в вашей группе;
добавить в настройках вашей игры платформу Групповое;
получить токен для работы с API групповых сообщений в вашей группе;
запросить у игрока разрешение на отправку ему сообщений от лица группы;
реализовать отправку сообщений пользователям с помощью API групповых сообщений.

Получение прав для приложения

Для получения доступа к сообщений от группы вам необходимо запросить право BOT_API_INIT для вашей игры.

Сделать это можно, отправив заявку на почту api-support@ok.ru и указав в письме, что вам необходимо право BOT_API_INIT для реализации механизма отправки сообщений от группы игры её игрокам.

В данный момент право выдаётся только игровым приложениями, размещенным в игровом каталоге Одноклассников.

Подробнее о запросе прав для приложения

Настройка группы

Для правильной работы сообщений вам требуется:

привязать группу к игре в настройках игры;
включить групповые сообщения в настройках группы;
получить токен для работы с API групповых сообщений в настройках группы.

Привязка группы к игре

Для этого вам потребуется:

зайти на страницу игры на версии Одноклассников для десктопа;
перейти в настройки приложения, нажав на кнопку Изменить настройки приложения в футере страницы игры;
указать нужную вам группу в настройках в поле Официальная группа.

Сменить настройки приложения может разработчик, либо владелец игры.

Указать группу в настройках приложения может модератор, супермодератор, либо администратор группы.

Подробнее о редактировании настроек приложения

Включение сообщений в группе

Для этого вам потребуется:

зайти на страницу группы на версии Одноклассников для десктопа;
перейти в настройки сообщений группы: Настройки -> Сообщения, либо по ссылке вида https://ok.ru/group/groupId/settings/messages, где groupId - id вашей группы
включить сообщения для всех, выбрав у настройки Сообщения могут писать значение Гости и участники. В случае, если ваша группа является закрытой, то допустимо включать сообщения только для участников группы, но в данном случае вы не сможете отправлять сообщения игрокам, которые не вступили в группу игры.

Включить функционал сообщений в группе может супермодератор, либо администратор группы.

Получение токена для работы с API

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

Для получения токена вам необходимо:

перейти в настройки сообщений группы;
нажать на кнопку Получить ключ доступа
в появившемся окне подтвердить получение токена
этот токен далее будет использоваться для работы с API групповых сообщений

Подробнее о групповых сообщениях

Запрос прав у пользователя

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

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

Проверка возможности отправки сообщений

Для проверки того, есть ли возможность отправки сообщения пользователю, необходимо использовать метод group.isMessagesAllowed

Метод требуется вызывать перед запросом права на отправку сообщений в рамках сессии пользователя, которая выдается в момент запуска игры.

Если метод вернул true, то право запрашивать не требуется.

Если метод вернул false, то требуется запросит право BOT_API_INIT у пользователя.

Запрос права

Запрос прав производится с помощью FAPI-метода FAPI.UI.showPermissions. Метод поддерживается на всех платформах.

Пример вызова:

    FAPI.UI.showPermissions(["BOT_API_INIT"]);

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

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

Для отправки сообщений требуется использовать API групповых сообщений с токеном, который вы получили ранее.

В простейшем случае для отправки сообщения пользователю по его ID вам будет необходим метод .

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

URL запроса

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

Тело запроса

{
    "recipient":{
        "user_id": "user:123456789012"              /* Id пользователя-получателя в формате user:id или id*/
    },
    "message":{                                     /* Содержимое сообщения */
        "text":"Hello"                              /* Текст сообщения */
    }
}

В случае успешной отправки вам будет возвращен такой ответ:

{
  "success": [
    true
  ],
  "chat_ids": [
    "chat:C401b13206b00"
  ]
}

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

{
  "success": [
    false
  ],
  "chat_ids": [
    null
  ]
}

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

Другие возможности групповых сообщений

Кроме отправки простых текстовых сообщений API групповых сообщений предоставляет множество других возможностей.

С помощью Bot API вы можете:

получать информацию о всех чатах группы с помощью метода GET graph.user.chats;
получать информацию о конкретном чате группы с помощью метода GET graph.user.chat;
получать прямую ссылку на чат с помощью метода GET graph.chat.url;
загрузить файл в чат с помощью метода GET graph.user.fileUploadUrl;
получать сообщения конкретного чата группы с помощью метода GET graph.chat.messages;
писать новые сообщения в конкретный чата группы с помощью метода POST graph.chat.messages;
подписаться на новые события в чатах группы с помощью метода POST graph.user.subscribe;
отписаться от получения новых событий в чатах группы с помощью метода POST graph.user.unsubscribe;
просмотреть список Webhook’ов, на которые отсылаются новые события в чатах с помощью метода GET graph.user.subscriptions.
получать обновления в чатах при наличии long polling-подписки с помощью метода GET graph.user.updates.