Developers » Callback API
Callback API
1. Connecting Callback API
2. Data Format
3. Example Usage

Callback API is a tracking tool for users activity in your VK communities. It allows to implement some useful features such as:
  • A bot for incoming messages analysis;
  • Automatic content moderation system;
  • A service to collect and process audience involvement factors.

To start using Callback API connect your server in the community settings and choose event types to be received (new comments and new photos for example). When desired event happens, VK will send a request in JSON format to your server containing data about an object that has triggered the event (for example a new comment). There is no need to send constant API requests to track updates anymore, now you will receive them right away.
1. Connecting Callback API

To connect Callback API open the "Manage community" page and pass to the "API Usage" tab. Then you need to specify and verify the server endpoint which will receive all further requests.

Confirmation is automatic: when you specify the server address and press the "Confirm" button, a request will be sent to your server. The server should return a required string.


After confirmation you will get access to notifications settings:


In the "Requests" tab you can see events history and content of requests sent to your server.

N.B.: After receiving a notification your server should return the "ok" string and HTTP 200 status. If a server returns several errors in a row, Callback API will temporarily stop sending notifications to it.
2. Data Format

When an event happens you get a JSON object in following format:
{"type": <event type>, "object": <object that has triggered the event>}

For example:
{"type": "group_join", "object": {"user_id": 1, "join_type" : "approved"}}

Objects structure in the object field depends on notification type. All event types and corresponding objects supported by Callback API are described below:

РазделТип событияФормат поля object
Messagesmessage_new
new message received
message_reply
new message sent
Private message object.
message_allow
new user consent to messages sending
Object with the following fields:
messages_deny
new user prohibition to messages sending
Object with the only field user_id (integer) — user ID.
Photosphoto_new
new photo in a community
Photo object.
photo_comment_new
new photo comment
photo_comment_edit
editing a photo comment
photo_comment_restore
restoring a photo comment
Comment object with additional fields:
  • photo_id (integer) — photo ID;
  • photo_owner_id (integer) — photo owner ID.
photo_comment_delete
deleting a photo comment
Object with following fields:
  • owner_id (integer) — photo owner ID;
  • id (integer) — comment ID;
  • user_id (integer) — ID of the user who deleted a comment;
  • photo_id (integer) — photo ID.
Audioaudio_new
new audio in a community list
Audio object
Videovideo_new
new video in a community list
Video object
video_comment_new
new video comment
video_comment_edit
editing a video comment
video_comment_restore
restoring a video comment
Comment object with additional fields:
  • video_id (integer) — video ID;
  • video_owner_id (integer) — video owner ID.
video_comment_delete
deleting a video comment
Object with following fields:
  • owner_id (integer) — video owner ID;
  • id (integer) — comment ID;
  • user_id (integer) — ID of the user who deleted a comment;
  • video_id (integer) — video ID.
Wall postswall_post_new
adding a post on wall
wall_repost
new repost
Wall post object
from_id contains positive values for posts from users.
Wall commentswall_reply_new
new comment on wall
wall_reply_edit
editing a comment on wall
wall_reply_restore
restoring a comment on wall
Comment object with additional fields:
  • post_id (integer) — post ID;
  • post_owner_id (integer) — post owner ID.
wall_reply_delete
deleting a comment on wall
Object with following fields:
  • owner_id (integer) — wall owner ID;
  • id (integer) — comment ID;
  • user_id (integer) — ID of the user who deleted a comment;
  • post_id (integer) — post ID.
Boardsboard_post_new
new comment in a board
board_post_edit
editing a board comment
board_post_restore
restoring a board comment
Board comment object with additional fields:
  • topic_id (integer) — topic ID;
  • topic_owner_id (integer) — topic owner ID.
board_post_delete
deleting a board comment
Object containing following fields:
  • topic_id (integer) — topic ID;
  • id (integer) — comment ID.
Marketmarket_comment_new
new comment to a market item
market_comment_edit
editing a market comment
market_comment_restore
restoring a market comment
Comment object with additional fields:
  • market_owner_id (integer) — market owner ID.
  • item_id (integer) — market item ID.
market_comment_delete
deleting a market comment
Объект, содержащий следующие поля:
  • owner_id (integer) — market owner ID;
  • id (integer) — comment ID;
  • user_id (integer) — ID of the user who deleted a comment;
  • item_id (integer) — market item ID.
Othergroup_leave
member removed from a community
Object with following fields:
  • user_id (integer) — user ID.
  • self (integer, [0,1]) — value describing if a user has left on his own or was deleted.
group_join
new member or join request
Object with following fields:
  • user_id (integer) — user ID.
  • join_type (string) — shows how exactly the user has joined. Possible values:
    • join — user joined a group or event (subscribed a public page).
    • unsure — for events: user has chosen "I may attend".
    • accepted — user approved an invitation to a group or event.
    • approved — a join request was approved by community administrators.
    • request — user sent a join request.
poll_vote_new
new vote in a public poll
Object with following fields:
  • owner_id (integer) — poll owner ID;
  • poll_id (integer) — poll ID;
  • option_id (integer) — option ID;
  • user_id (integer) — user ID.
group_officers_edit
changes in the administrators list
Object with following fields:
  • admin_id (integer) — ID of the administrator who made changes;
  • user_id (integer) — ID of the user whose role has been changed;
  • level_old (integer) — old role;
  • level_new (integer) — new role.
level_old and level_new fields can take following values:
  • 0 — no role;
  • 1 — moderator;
  • 2 — editor;
  • 3 — administrator.
group_change_settings
changes in a community settings
Object with following fields:
  • user_id — ID of the user who made changes;
  • changes — changes description. Object with following fields:
    • {FIELD} — section name. {FIELD} can take values:
      • title — title;
      • description — description;
      • access — community type;
      • screen_name — screen name;
      • public_category — public category;
      • public_subcategory — public subcategory;
      • age_limits — age limits;
      • website — website;
      • enable_{SECTION} — {SECTION} can take values: status_default, audio, photo, video, market.
    • old_value — old value;
    • new_value — new value.
group_change_photo
changes of community main photo
Object with following fields:
  • user_id — ID of the user who made changes;
  • photo — object describing a photo.
3. Example Usage
In our example PHP script processes notifications about new message and sends an answer to his author.

<?php

if (!isset($_REQUEST)) {
return;
}

//Confirmation code from Callback API settings
$confirmation_token = 'd8v2ve07';

//Community access_token
$token = 'c0223f775444cf3d58a8a1442ec76a9571c8f58e3e24616d9440f73dc43022bbead9b2e576cb41d09c0a1';

//Receive and decode notification
$data = json_decode(file_get_contents('php://input'));

//Check the "type" field
switch ($data->type) {
//If this is a confirmation message...
case 'confirmation':
//...send confirmation code
echo $confirmation_token;
break;

//If this is a new message...
case 'message_new':
//...get his author ID
$user_id = $data->object->user_id;
//then get user info via users.get method
$user_info = json_decode(file_get_contents("https://api.alliance-tools.ru/method/users.get?user_ids={$user_id}&v=5.0"));

//and get his name from the response
$user_name = $user_info->response[0]->first_name;

//Send an answer with messages.send method and community access_token
$request_params = array(
'message' => "Hello, {$user_name}!",
'user_id' => $user_id,
'access_token' => $token,
'v' => '5.0'
);

$get_params = http_build_query($request_params);

file_get_contents('https://api.alliance-tools.ru/method/messages.send?'. $get_params);

//Re