VK (VKontakte)

VK (VKontakte)

This connector calls the VK API (https://api.vk.ru/method/<method>, version 5.199) for a VK community (сообщество): community information, community messages, comments as the community, and, with an optional user token, the wall, statistics, shop products and photo albums.

Two kinds of token VK decides per method which token it accepts, and a community token cannot call every method.

• VK_COMMUNITY_TOKEN (required) is a community access key (ключ доступа сообщества). It works for vk_get_token_permissions, vk_get_community, vk_list_conversations, vk_get_conversation_history, vk_send_message and vk_create_comment.
• VK_USER_TOKEN (optional) is a user access key of a community admin. VK accepts only user tokens for vk_publish_post, vk_get_community_stats, vk_list_market_products and the delete tools. vk_get_wall_posts, vk_get_post_comments and vk_list_photo_albums also accept a service key (сервисный ключ) of your VK ID app, for public communities. Without it these tools stop before calling VK and say that the variable is missing; a community token there would be refused with error 27.

Setup of the community token (about 3 minutes, self-service)

1. Open the community, then Manage > Advanced > API usage (Управление > Дополнительно > Работа с API), tab Access keys (Ключи доступа), and click Create key.
2. Tick the rights the tools need: Community management (управление сообществом), Community messages (сообщения сообщества), Wall (стена) for comments, Photos if needed. Confirm in the VK app or by SMS.
3. Copy the key into VK_COMMUNITY_TOKEN. Community keys do not expire; delete and recreate the key if it leaks.
4. For messages, also switch on Community messages (Сообщения сообщества) under Manage > Messages.

User token (optional): VK issues user tokens through VK ID apps (https://id.vk.ru/business/go). The wall and market rights are granted to an app only on request to VK support, and VK ID access tokens are short-lived unless issued with offline access, so a static VK_USER_TOKEN suits accounts that already have such a token. A service key from the app settings is enough to read public walls, comments and photo albums.

Errors: VK answers HTTP 200 with an error object; the connector turns it into a failed call. Error 5 means the token is wrong or revoked; 15 or 7 means the token lacks the right (check vk_get_token_permissions); 27 means the method does not accept community tokens (set VK_USER_TOKEN); 6, 9 and 29 are rate limits (wait and retry later); 100 means a wrong or missing parameter; 901 and 902 mean the user has not allowed messages from the community.

Ids: a community has a positive id (community_id, group_id) and appears as a negative owner_id on its wall; the tools build the negative form themselves. vk_get_community returns the id and the short address (screen_name) that vk_get_wall_posts takes. A conversation is addressed by peer_id (the user id in a private chat). Dates are Unix time in seconds.

Where to start: vk_get_token_permissions and vk_get_community need no arguments. For messages call vk_list_conversations with filter = unanswered, then vk_get_conversation_history with the peer_id.

Writes: vk_send_message, vk_create_comment and vk_publish_post are public or reach a person at once. Show the user the exact text, the recipient or the community, and wait for confirmation before each one. Give every message a new random_id and reuse it only to retry the same message. The delete tools are installed switched off.

Rate limits: a community token allows about 20 requests a second, a user token 3. Messaging users who never wrote to the community is limited and may be refused.

Out of scope: uploading photos or videos (attach media that is already on VK), ads, Callback and Long Poll events, member management and bans, polls, stories and personal (non-community) messages.