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.
To user this feature your app requires to have a BOT_API_INIT permission.
To get it send a request to email@example.com 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.
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.
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
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.
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.
If message was sent successfully following response will be returned:
If an error happened you will get this response:
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:
- get information about all chats via method GET graph.user.chats;
- get information about a specific chat via method GET graph.user.chat;
- get direct link to a chat via method GET graph.chat.url;
- upload a file to a chat via method GET graph.user.fileUploadUrl;
- get specific chat’s messages via method GET graph.user.messages;
- send new messages to group chats via method POST graph.user.messages;
- subscribe to all new chat events via method POST graph.user.subscribe;
- unsubscribe from all new chat events via method POST graph.user.unsubscribe;
- view a list of current new events subscriptions via method GET graph.user.subscriptions.