Entwickler » API for Chatbots
API for Chatbots
Implementation Examples 1. Community
1.1. Acquiring The Access Token
2. Receiving Events And Updates
2.1. Callback API
2.2. Long Poll
3. Bot Messages
3.1. Sending Messages
3.2. Attachments
A chatbot is a script on your server that receives notifications about new VK events and processes them. For example, it determines a text command in a message from a user and sends some image in response.
To create bots, you need:
- a community from which the bot can communicate with VK users.
- a server that will receive event notifications.
- the bot’s logic. In other words, the script that establishes how a bot responds to an event.
First, the chatbot’s functionality needs to be determined. Then create a list of possible text commands or events to which the bot should react to and appropriate actions the bot may take. Be aware that people may make mistakes while writing commands and send the bot text that differs from options you considered. It is impossible to foresee this action each time. In this case, you can send the user a list of all supported commands.
If you have not worked with the VK API, we recommend you read this manual before beginning work.
Implementation examples
PHP
The VK PHP bot was created by our developers in PHP. Callback API is used for processing events, and voice messages are generated with the API Yandex Speechkit. The project code is on GitHub:
Java
A bot for working with Youtrack, it was created by our developers in Java (Java SDK). Callback API is used for processing events, and the project code is on GitHub:
JS
A library developed by Mikhail Semin for working with codes on Node JS. Long Poll is used to quickly and comfortably add new commands and responses. The project code is on GitHub:
If you want to add your project to this list, message us at api@vk.com.
1.Communities
You can connect a chatbot to any VK community, whether it is a group, event or public page. Your bot must comply with the rules, about which you can learn more here.
Communities are entrances for users who want to communicate with your bot. Make sure that the community looks appealing and contains a description of your bot, or else its actions may surprise users. Don’t forget to enable messages in your community (“Manage community” -> “Messages”) when the bot is ready for use so that users can send messages to your community.
So, if you have chosen a community, you may begin configuring notification settings.
1.1 Acquiring The Access Token
The access token is necessary for receiving updates (in Long Poll) as well as working with the API.
Open the section “Manage ñommunity” (“Manage ñage” if you have a public page), choose the tab “API Usage” and click on “Create token”.
Select the required access rights and confirm your choice.
You can create several tokens with different access rights. Tokens cannot be displayed publically as a third party may access the VK API on behalf of your community using your access token. If the token has been compromised, delete it from the list in order to invalidate it.
Additionally, you can acquire the access token using OAuth. Use the Authorization Code Flow scheme.
2. Receiving Events And Updates
To respond to certain events, your script must know them. For this to happen, two possible solutions exist, Callback API and Long Poll.
2.1 Callback API
Callback API sends notifications to your server as soon as some compulsory event happens in a community. The event can be anything from photo comments, new wall posts, community subscriptions, sending messages and many more. The full list of available events, as well as learning more about settings, can be found in the Callback API documentation. To enable Callback API in a community, indicate the script address in your server and select the events you wish to receive. For example, if your bot should recognize text commands, select the event “Incoming messages”.
A Callback API notification looks like JSON with the basic event information:
{
"type":"message_new",
"object":{
"id":694,
"date":1499441696,
"out":0,
"user_id":123456,
"read_state":0,
"title":" ... ",
"body":"start"
},
"group_id":1,
"secret":"sjr948dff3kjnfd3"
}
In this example, a user with ID 123456 sent the message “start” to a community.
For every event, Callback API sends a separate request to your server. Your script must confirm the receipt of every request by sending “ok” in each response.
PHP example
define('ÑALLBACK_API_EVENT_CONFIRMATION', 'confirmation');
define('ÑALLBACK_API_EVENT_MESSAGE_NEW', 'message_new');
define('CALLBACK_API_CONFIRMATION_TOKEN', '213fefef3');
$event = json_decode(file_get_contents('php://input'), true)
switch ($event['type']) {
//Ïîäòâåðæäåíèå ñåðâåðà
case ÑALLBACK_API_EVENT_CONFIRMATION:
echo(CALLBACK_API_CONFIRMATION_TOKEN);
break;
//Ïîëó÷åíèå íîâîãî ñîîáùåíèÿ
case ÑALLBACK_API_EVENT_MESSAGE_NEW:
echo('ok');
break;
default:
echo('Unsupported event');
break;
}
Full script on GitHub
2.2 Long Poll
The second way of receiving updates is connecting to the Long Poll server. Unlike Callback API, the Long Poll server will send only those updates that are related to messages. No other events from the community will be sent. To learn more about working with the Long Poll server, go to this page. The Long Poll server response looks like an array of updates in JSON. This is how a separate event appears:
[
4,
2105994,
561,
123456,
1496404246,
"hello",
{
"attach1_type":"photo",
"attach1":"123456_417336473",
"attach2_type":"audio",
"attach2":"123456_456239018",
"title":" ... "
}
]
In this example, a user with ID 123456 sent the message “hello” with an audio and a photo attachments.
Long Poll sent several events in response to your request. To receive all updates immediately, remain constantly connected to Long Poll.
Continue