Group messages

Via OK API you can send messages from your game’s official group to players.

You can send messages to single users or to multiple of them at once.

How to enable group messages

To enable group messages you need to follow these steps:

  • request BOT_API_INIT permission for your app;
  • enable group messages in group settings;
  • add Group platform to your app;
  • get access token for Bot API in group settings;
  • request a permission to send messages from user on app’s start.

Requesting permissions

To user this feature your app requires to have a BOT_API_INIT permission.

To get it send a request to api-support@ok.ru and specify that you need a BOT_API_INIT permission for your game in a request.

Permission is granted to any game applications launched on our platform.

More about app permissions

Setting up a group

Before implementing a feature in your game you need to set up a group from which messages will be sent:

  • link a group to your app;
  • enable group messages in it’s settings;
  • get a token to work with Bot API.

Linking a group to an app

Follow these step to link a group to your app:

  • go to your game’s page on OK;
  • proceed to it’s settings by pressing a App settings button in game’s page footer;
  • specify a group in a Официальная группа field.

To access app’s settings you have to be it’s owner or a developer.

To link a group you have to be at least a moderator in it.

More about app settings

Enabling group messages

How to enable messages in a group:

  • open group page on OK;
  • open it’s settings: Settings -> Messages, or use a link https://ok.ru/group/groupId/settings/messages
  • enable group messages by setting Messages can be sent by field’s value to Guests and participants. If your group is closed than you can allow messages for participants only.

To enable group messages in a group you have to be a super moderator or administrator in it.

Getting an API token

After you’ve enabled group messages you can get a token to work with Bot API.

To get a token you should:

  • open group messages settings page;
  • press a Generate access token button;
  • press a button to get a token
  • this token can be then used to call Bot API methods

More about group messages

Requesting a permission from user

By default an app can’t send messages to users. To make it possible user needs to permit you to send them.

Before requesting a permission you should check if user is already permitted you to send messages.

Checking a permission

To check if messages are already enable use this method: group.isMessagesAllowed

Method should be call within user session that is provided to a game by our platform on game’s launch.

true response means messages are already enabled and you don’t need to request a permission from user.

false response means BOT_API_INIT should be requested from user.

Requesting a permission

To request a permission use FAPI method FAPI.UI.showPermissions. Method is supported on all platforms.

Example usage:

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

After method is called a layer will be shown to a user where he could either permit or deny a request.

Sending a message

To send messages use group messages API using a token you got earlier.

In a simplest case method can be used to send a text message to user.

Example usage

Request URL

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

Request body

{
    "recipient":{
        "user_id": "user:123456789012"              /* user id in a user:id or id format */
    },
    "message":{                                     /* message body */
        "text":"Hello"                              /* message content */
    }
}

If message was sent successfully following response will be returned:

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

If an error happened you will get this response:

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

If an error was returned it will be useful to check if user has enabled messages from group.

Other Bot API methods

With Bot API you can do the following things: