Messages from the group of the game

The OK platform allows you to organize communication between the game and players with help of messages in the chat for the group of the game and users.

This will let you both notify users of various in-game events in a most efficient way by bulk messaging and/or sending messages to specific users and keep in touch with your audience.

How to enable it

To use messages from the group of the game, users have to do the following:

• request a BOT_API_INIT right for your game;
• enable the group message support in your group;
• add the “Group” platform in the settings of your game;
• get a token for working with the group message API in your group;
• request for players’ consent for sending messages on behalf of the group to them;
• start sending messages to users with help of the group message API.

How to get rights for an application

To get access to messages from the group, you have to request a BOT_API_INIT right for your game.

You can do it by e-mailing a request to api-support@ok.ru. Mention that you need the BOT_API_INIT right in order to send messages from the group to players.

At the moment, this right is given only to game applications listed in the OK game catalog.

More on how to request rights for an application

Group settings

For messages to function correctly, you have to:

• link a group to the game in the game settings;
• enable group messages in the group settings;
• get a token for working with the group message API in the group settings.

How to link a group to the game

Do the following:

• go to the game page on the desktop OK version;
• go to the game settings by pressing the “Change application settings” button in the footer of the game page;
• enter the name of the group you need in the “Official group” field.

Application settings can be changed by the developer or the game owner.

The group can be listed in the application settings by the moderator, the super moderator or the group administrator.

More on how to edit the application settings

How to enable messages in the group

Do the following:

• go to the group page on the desktop OK version;
• go to settings of messages from the group: Settings -> Message, or go to the link https://ok.ru/group/groupId/settings/messages, where groupId is the id of your group
• enable messages for everyone by choosing “Guests and participants” values for “Can write messages” in settings. If your group is private, it is enough to enable messages for participants of the group. However, you will not be able to send messages to players who have not joined the game group.

The function to send messages from the group can be enabled by the super moderator or the group administrator.

How to get a token for working with the API

After enabling messages from the group, you will be able to generate a token for working with the group message API.

To get the token, do the following:

• go to settings of messages from the group;
• press the “Get the access key” button
• confirm the reception of the token in the window that appears
• this token will be used for working with the group message API

More on group messages

How to request rights from users

At first, it is impossible to send messages to players. To be able to do so, they must allow you to send messages from the group to them.

Before requesting a right to do so, check if the user has given it to you before and if they have enabled messages from the group.

How to check if you can send messages

In order to check if you can send messages to a user, use the group.isMessagesAllowed method.

You need to call the method before requesting the right to send messages within the user session which is given in the moment of launching the game.

If the method returned “true”, you don’t need to request the right.

If the method returned “false”, you have to request the BOT_API_INIT right from the user.

How to request the right

You can request rights with help of the FAPI.UI.showPermissions FAPI method. This method is supported on all platforms.

Call example:

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

As a call result, the user will see a pop-up window where they can either allow sending messages to them or refuse:

How to send messages

In order to send messages, you need to use the group messages API with the token you have received earlier.

In the simplest case, you will need the method to send a message to a user via their ID.

Request example

Request URL

Request body

{
"recipient":{
"user_id": "user:123456789012"              /* Id of the recipient in a user:id or id format */
},
"message":{                                     /* Contents of the message */
"text":"Hello"                              /* The text of the message */
}
}

If the message was successfully sent, you will receive the following answer:

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

In case if the user disabled messages from the group or an error occurred, you will receive the following answer:

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

If you received a negative answer during the user’s next launch of the game, check if they have enabled messages from the group. If they have not, send a request to do so again (optional).

Other capabilities of group messages

Aside from sending simple text messages, the group messages API has many other capabilities.

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

• get information on all chats in the group with the GET graph.user.chats method;
• get information on a specific chat in the group with the GET graph.user.chat method;
• receive a direct link to a chat with the GET graph.chat.url method;
• upload a file with the GET graph.user.fileUploadUrl method;
• upload a file with the GET graph.chat.messages method;
• write new messages for a specific chat in the group with the POST graph.chat.messages method;
• subscribe to new events within chats in the group with the POST graph.user.subscribe method;
• unsubscribe from new events within chats in the group with the POST graph.user.unsubscribe method;
• view a list of Webhooks that new events in chats refer to with the GET graph.user.subscriptions method;
• receive updates in chats with a long-polling subscription present with the GET graph.user.updates method.