1. Connecting
2. Answer Format
3. Event Structure
    3.1. Extra Message Fields
4. Message Flags
5. Dialog Flags
6. Attachments
7. Platforms
8. Event Examples

Long polling – this is a technology that allows the receiving of information about new events with the help of "long requests". The server receives the request but it doesn't immediately send the answer but rather when some event will happen (for example, receiving a new incoming message), or waiting period is over.

By using this approach, you can instantly display in your app the most important events. Be aware that with the help of Long Poll, you won't be able to send messages. For this, you’ll need to use the messages.send method.

This documentation corresponds to version 2.

If you use previous versions, please note the list of changes:

• messages.getLongPollServer method takes lp_version parameter.
• Instead of a set of events 3 one event 3 comes for the read dialog.
• Instead of a set of events 2 one event 13 comes for the deleted dialog.
• Empty subject of message will not come ($subject field is absent).
• +2 flag of communities dialogs has been inverted — now it corresponds to an unanswered dialog.
• +65536 flag for messages has been added — it corresponds to a greeting message, dialog with that should not be raised in the dialogs list.

Before connecting to the Long Poll server, you will need to acquire the session data (server, key, ts) using the messages.getLongPollServer method.

Afterwards, leave this kind of request:

https://{$server}?act=a_check&key={$key}&ts={$ts}&wait=25&mode=2&version=1

Following parameters are used in the request:

• key — secret session key;
• server — the server address to which you need to send the request;
• ts — the number of the last event from which you want to receive data;
• wait — the waiting period (as most proxy servers terminate the connection after 30 seconds, we recommend indicating wait = 25). Maximum: 90.
• mode — additional answer options. A list of necessary option codes:
  • 2 — receive attachments;
  • 8 — return an expanded set of events;
  • 32 — return pts (it's required for the messages.getLongPollHistory method operation without a limit of the most recent 256 events);
  • 64 — for the event with code 8 (a friend is online), extra data is returned in the field $extra (learn more in the Event Structure section);
  • 128 — return the parameter random_id with a message (random_id can be transferred while sending messages using the messages.send method);
• version — actual version: 2. For version 0 (default), community IDs will arrive in the format group_id + 1000000000 for saving backward compatibility. We recommend using the updated version.

For the first request within a session, values for the server, key and ts parameters are to be received by the messages.getLongPollServer method. For next requests, use the same server and key values and a new value for ts that will be sent to you in a request from the Long Poll server.

When a new event happens or the waiting period passes, you will receive an answer from the server in JSON-format:

{"ts":1820350874,"updates":[­[4,1619489,561,123456,1464958914," ... ","hello", {"attach1_type":"photo","attach1":"123456_414233177", "attach2_type":"audio","attach2":"123456_456239018"}]]}

JSON-object in answer contains two fields:

• ts (integer) — number of the last event. Use this value in the next request.
• updates (array) — array whose elements contain the presentation of new events (each element, in turn, is an array). The updates array length can be equal to zero (this means that no events happened during the wait time). Further details about the element structure in the updates array can be learned in the Event Structure section.

After receiving any answer to continue the connection, you will need to send a new request with a new ts, which is received in the last answer.

Also as an answer to a request, the server may return one of these mistakes:

{"failed":1,"ts":$new_ts}
{"failed":2}
{"failed":3}
{"failed":4,"min_version":0,"max_version":1}

• "failed":1 — the event history went out of date or was partially lost, the app can continue receiving events using the new ts value from the answer
• "failed":2 — the key’s active period expired. It's necessary to receive a key using the messages.getLongPollServer method.
• "failed":3 — user information was lost. It's necessary to request a new key and ts with the help of the messages.getLongPollServer method.
• "failed":4 — an invalid version number was passed in the version parameter.

Be aware that in some cases, objects in messages by mistake may contain extra fields that aren’t described in the documentation. Ignore them and don’t try to work with them.

Each element of the updates array represents its own an array that contains the event code in the first element and some set of fields with additional information depending on the type of event.

Be aware that in some cases, the answer may contain additional events and codes which are not represented in this table. Ignore them and don’t try to work with them.

Code	Extra fields	Event description
1	$message_id (integer) $flags (integer) [extra_fields]*	Replace message flags (FLAGS:=$flags).
2	$message_id (integer) $mask (integer) [extra_fields]*	Install message flags (FLAGS|=$mask).
3	$message_id (integer) $mask (integer) [extra_fields]*	Reset message flags (FLAGS&=~$mask).
4	$message_id (integer) $flags (integer) [extra_fields]*	Add a new message.
5	$message_id (integer) $mask(integer) $peer_id(integer) $timestamp(integer) $new_text(string) [$attachments](array) 0	Edit message.
6	$peer_id (integer) $local_id (integer)	Read all incoming messages received before message with $local_id.
7	$peer_id (integer) $local_id (integer)	Read all outgoing messages sent before message with $local_id.
8	-$user_id (integer) $extra (integer) $timestamp(integer)	A friend $user_id is online. $extra is not 0, if flag 64 was passed in mode. The low byte (remaining from the division into 256) of an extra number contains the platform ID (ref. 7. Platforms). $timestamp is a time of the last action of $user_id user.
9	-$user_id (integer) $flags (integer) $timestamp(integer)	A friend $user_id is offline ($flags is 0, if the user left the website (for example, by pressing Log Out) and 1, if offline is due to timing out (for example, the away status)). $timestamp is a time of the last action of $user_id user.
10	$peer_id (integer) $mask (integer)	Reset dialog flags $peer_id. Corresponds to the operation (PEER_FLAGS &= ~$flags). An event is returned only for community messages.
11	$peer_id (integer) $flags (integer)	Replace dialog flags $peer_id. Corresponds to the operation (PEER_FLAGS:= $flags). An event is returned only for community messages.
12	$peer_id (integer) $mask (integer)	Install dialog flags $peer_id. Corresponds to the operation (PEER_FLAGS|= $flags). An event is returned only for community messages.
13	$peer_id (integer) $local_id (integer)	Deletings all messages in $peer_id dialogs with IDs up to $local_id.
51	$chat_id  (integer) $self (integer)	One of the parameters (content, topic) of the conversation $chat_id was changed. $self — 1 or 0 (whether the change was caused by the user).
61	$user_id  (integer) $flags (integer)	User $user_id began typing in the dialog. The event should happen once in ~5 seconds during continuous typing. $flags = 1.
62	$user_id  (integer) $chat_id (integer)	User $user_id began typing in the conversation $chat_id.
70	$user_id  (integer) $call_id (integer)	User $user_id completed a call with the ID $call_id.

Part 2