ДокументацияAPIСообществоСоздать приложение
Войти

User Long Poll API

Long Polling — это технология, которая позволяет получать данные о новых событиях с помощью «длинных запросов». Сервер получает запрос, но отправляет ответ на него не сразу, а лишь тогда, когда произойдет какое-либо событие (например, придёт новое сообщение), либо истечет заданное время ожидания.

Используя этот подход, вы можете мгновенно отображать в своем приложении важные события. С помощью User Long Poll API вы не сможете отправить сообщение, для этого используйте метод messages.send.

Изменения в версиях

Документация соответствует версии 3.

Если вы используете более старую версию, обратите внимание на список изменений:

  • •
    Новый флаг для сообщений, удалённых для получателей — 131072.
  • •
    Вложения (geo, photo и т.д.) и дополнительные данные (title, from) приходят в отдельных объектах. См. Вложения и дополнительные данные.

Подключение

Перед подключением к Long Poll серверу необходимо получить данные сессии (server, key, ts) методом messages.getLongPollServer. Мы рекомендуем передавать актуальный номер версии Long Poll в параметре lp_version.

Затем составьте запрос такого вида:

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

В нём используются следующие параметры:

  • •
    key — секретный ключ сессии;
  • •
    server — адрес сервера;
  • •
    ts — номер последнего события, начиная с которого нужно получать данные;
  • •
    wait — время ожидания (так как некоторые прокси-серверы обрывают соединение после 30 секунд, мы рекомендуем указывать wait= 25). Максимальное значение — 90.
  • •
    mode — дополнительные опции ответа. Сумма кодов опций из списка:
    • •
      2 — получать вложения;
    • •
      8 — возвращать расширенный набор событий;
    • •
      32 — возвращать pts (это требуется для работы метода messages.getLongPollHistory без ограничения в 256 последних событий);
    • •
      64 — в событии с кодом 8 (друг стал онлайн) возвращать дополнительные данные в поле $extra (см. Структура событий);
    • •
      128 — возвращать поле random_id (random_id может быть передан при отправке сообщения методом messages.send).
  • •
    version — версия. Актуальная версия: 3. Для версии 0 (по умолчанию) идентификаторы сообществ будут приходить в формате group_id + 1000000000 для сохранения обратной совместимости. Мы рекомендуем использовать актуальную версию.

Для первого запроса в рамках сессии значения для параметров server, key и ts необходимо получить методом messages.getLongPollServer. В последующих запросах используйте те же server и key и новое значение ts, которое придет вам в ответе от Long Poll сервера.

Формат ответа

Когда произойдет новое событие или истечет время ожидания, сервер вернет вам ответ в формате JSON:

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

JSON-объект в ответе содержит два поля:

  • •
    ts (integer) — номер последнего события. Используйте его в следующем запросе.
  • •
    updates (array) — массив, элементы которого содержат представление новых событий (каждый элемент также является массивом). Длина массива updates может быть равна 0 (это означает, что за время wait новых событий не произошло). Подробнее о структуре элементов в массиве updates вы можете узнать в разделе: Структура событий.

После получения любого ответа для продолжения связи нужно отправить запрос с новым ts, полученным в последнем ответе. 

В ответ на запрос сервер может вернуть одну из ошибок:

JSON{"failed":1,"ts":$new_ts} {"failed":2} {"failed":3} {"failed":4,"min_version":0,"max_version":1}
  • •
    "failed":1 — история событий устарела или была частично утеряна, приложение может получать события далее, используя новое значение ts из ответа.
  • •
    "failed":2 — истекло время действия ключа, нужно заново получить key методом messages.getLongPollServer.
  • •
    "failed":3 — информация о пользователе утрачена, нужно запросить новые key и ts методом messages.getLongPollServer.
  • •
    "failed": 4 — передан недопустимый номер версии в параметре version.

Обратите внимание, объекты в сообщении об ошибке могут содержать поля, не описанные в документации. Их необходимо игнорировать и не пытаться обработать.

Структура событий

Каждый элемент массива updates — это массив, содержащий код события в первом элементе и некоторый набор полей с дополнительной информацией в зависимости от типа события.

Обратите внимание — ответ может содержать события, коды которых не представлены в этой таблице. Их нужно игнорировать и не пытаться обработать.

1

$message_id (integer) $flags (integer) extra_fields* Замена флагов сообщения (FLAGS:=$flags).

2

$message_id (integer) $mask (integer) extra_fields* Установка флагов сообщения (FLAGS=$mask).

3

$message_id (integer) $mask (integer) extra_fields* Сброс флагов сообщения (FLAGS&=~$mask).

4

$message_id (integer) $flags (integer) $minor_id(integer) extra_fields* Добавление нового сообщения.

5

$message_id (integer) $mask(integer) $peer_id(integer) $timestamp(integer) $new_text(string) $attachments(array) 0 Редактирование сообщения.

6

$peer_id (integer) $local_id (integer) Прочтение всех входящих сообщений в $peer_id, пришедших до сообщения с $local_id.

7

$peer_id (integer) $local_id (integer) Прочтение всех исходящих сообщений в $peer_id, пришедших до сообщения с $local_id.

8

-$user_id (integer) $extra(integer) $timestamp(integer) Друг $user_id стал онлайн. $extra не равен 0, если в mode был передан флаг 64. В младшем байте (остаток от деления на 256) числа extra лежит идентификатор платформы (см. Платформы). $timestamp — время последнего действия пользователя $user_id на сайте.

9

-$user_id (integer) $flags (integer) $timestamp(integer) Друг $user_id стал оффлайн ($flags равен 0, если пользователь покинул сайт и 1, если оффлайн по таймауту ) . $timestamp — время последнего действия пользователя $user_id на сайте.

10

$peer_id (integer) $mask (integer) Сброс флагов диалога $peer_id. Соответствует операции (PEER_FLAGS &= ~$flags). Только для диалогов сообществ.

11

$peer_id (integer) $flags (integer) Замена флагов диалога $peer_id. Соответствует операции (PEER_FLAGS:= $flags). Только для диалогов сообществ.

12

$peer_id (integer) $mask (integer) Установка флагов диалога $peer_id. Соответствует операции (PEER_FLAGS= $flags). Только для диалогов сообществ.

13

$peer_id (integer) $local_id (integer) Удаление всех сообщений в диалоге $peer_id с идентификаторами вплоть до $local_id.

14

$peer_id (integer) $local_id (integer) Восстановление недавно удаленных сообщений в диалоге $peer_id с идентификаторами вплоть до $local_id.

20

$peer_id (integer) $major_id (integer) Изменился $major_id в диалоге $peer_id.

21

$peer_id (integer) $minor_id (integer) Изменился $minor_id в диалоге $peer_id.

51

$chat_id (integer) $self (integer) Один из параметров (состав, тема) беседы $chat_id были изменены. $self — 1 или 0 (вызваны ли изменения самим пользователем).

52

$type_id (integer) $peer_id (integer) $info(integer) Изменение информации чата $peer_id с типом $type_id, $info — дополнительная информация об изменениях, зависит от типа события. См. Дополнительные поля чатов

61

$user_id (integer) $flags (integer) Пользователь $user_id набирает текст в диалоге. Событие приходит раз в ~5 секунд при наборе текста. $flags = 1.

62

$user_id (integer) $chat_id (integer) Пользователь $user_id набирает текст в беседе $chat_id.

63

$user_ids (integer) $peer_id (integer) $total_count (integer) $ts (integer) Пользователи $user_ids набирают текст в беседе $peer_id. Максимально передается пять участников беседы, общее количество печатающих указывается в $total_count. $ts — время генерации этого события.

64

$user_ids (integer) $peer_id (integer) $total_count (integer) $ts (integer) Пользователи $user_ids записывают аудиосообщение в беседе $peer_id.

70

$user_id (integer) $call_id(integer) Пользователь $user_id совершил звонок с идентификатором $call_id.

80

$count (integer) 0 Счетчик в левом меню стал равен $count.

114

$peer_id (integer) $sound (integer) $disabled_until (integer) Изменились настройки оповещений. $peer_id — идентификатор чата/собеседника, $sound — 1/0, включены/выключены звуковые оповещения, $disabled_until — выключение оповещений на необходимый срок (-1: навсегда, 0)

Дополнительные поля сообщений

  • •
    $peer_id (integer) — идентификатор назначения. Для пользователя: id пользователя. Для групповой беседы: 2000000000 + id беседы. Для сообщества: -id сообщества либо id сообщества + 1000000000 (для version = 0).
  • •
    $timestamp (integer) — время отправки сообщения в Unixtime;
  • •
    $text (string) — текст сообщения;
  • •
    [$attachments] (array) — вложения (если mode = 2);
  • •
    [$random_id] (integer) — random_id, если параметр был передан в messages.send. Может содержать 0, если значение не задано.

Если сообщение по каким-то причинам недоступно, extra_fields могут не возвращаться либо может возвращаться только $peer_id. В событиях 1, 2 и 3 в большинстве случаев возвращается только $peer_id. В событии 4 в большинстве случаев возвращается полный набор полей. Если сообщение было восстановлено, в событиях 1 и 3 (снятие флага SPAM или DELETED) в большинстве случаев вернётся полный набор полей.

Дополнительные поля чатов

  • •

    $type_id (integer) — идентификатор типа изменения в чате.

    • •
      1 — изменилось название беседы;
    • •
      2 — сменилась обложка беседы;
    • •
      3 — назначен новый администратор;
    • •
      4 — закреплено сообщение;
    • •
      5 — пользователь присоединился к беседе;
    • •
      6 — пользователь покинул беседу;
    • •
      7 — пользователя исключили из беседы;
    • •
      8 — с пользователя сняты права администратора.
  • •

    $info (integer) — дополнительная информация об изменениях в чате. Значение зависит от type_id.

    • •
      type_id = 1, 2 — $info = "0";
    • •
      type_id = 3 — $info = "admin_id";
    • •
      type_id = 5 — $info = "conversation_message_id";
    • •
      type_id = 6, 7, 8 — $info = "user_id";

Флаги сообщений

Каждое сообщение имеет флаг — значение, полученное суммированием любых из следующих параметров.

+1

UNREAD Сообщение не прочитано

+2

OUTBOX Исходящее сообщение

+4

REPLIED На сообщение был создан ответ

+8

IMPORTANT Помеченное сообщение

+16

CHAT Сообщение отправлено через чат.

Обратите внимание, этот флаг устаревший и вскоре перестанет поддерживаться.

+32

FRIENDS Сообщение отправлено другом. Не применяется для сообщений из групповых бесед.

+64

SPAM Сообщение помечено как спам.

+128

DELЕTЕD Сообщение удалено (в корзине)

+256

FIXED Сообщение проверено пользователем на спам.

Обратите внимание, этот флаг устаревший и вскоре перестанет поддерживаться.

+512

MEDIA Сообщение содержит медиаконтент.

Обратите внимание, этот флаг устаревший и вскоре перестанет поддерживаться.

+65536

HIDDEN Приветственное сообщение от сообщества. Диалог с таким сообщением не нужно поднимать в списке (отображать его только при открытии диалога напрямую). Флаг недоступен для версий <2.

+131072

DELETE_FOR_ALL Сообщение удалено для всех получателей. Флаг недоступен для версий <3.

+262144

NOT_DELIVERED Входящее сообщение не доставлено. Присылается сброс этого флага в случае доставки входящего сообщения у которого был TTL.

Значения, не представленные в таблице, следует игнорировать и не пытаться каким-либо образом обработать.

Флаги диалогов

Каждый диалог имеет флаги — значение, полученное суммированием любых из следующих параметров. Флаги назначаются только для диалогов сообщества.

+1

IMPORTANT Важный диалог

+2

UNANSWERED Неотвеченный диалог. Обратите внимание, для версий <2 значение флага противоположно — диалог с ответом от сообщества.

Значения, не представленные в таблице, следует игнорировать и не пытаться каким-либо образом обработать.

Вложения и дополнительные данные

Если mode содержит флаг 2, то вместе с текстом и заголовком сообщения может быть передан JSON-объект, содержащий медиавложения. Ниже приведено описание полей этого объекта.

Обратите внимание — в некоторых случаях ответ может содержать дополнительные вложения, названия которых не представлены в этой таблице. Их необходимо игнорировать и не пытаться каким-либо образом обработать.

attach{$i}_type photo, video, audio, doc, wall, sticker, link, money Тип $i-го прикрепления, где i > 0.

attach{$i} {$owner_id}_{$item_id} Идентификатор $i-го прикрепления, где i > 0.

fwd {$user_id}_{$msg_id},{$user_id}_{$msg2_id},... Обратите внимание, этот тип вложения устарел и в будущем перестанет использоваться. Идентификаторы пересланных сообщений.

geo {$geo_id} Идентификатор прикрепленной карты. Следует рассматривать это вложение только как признак того, что к сообщению прикреплена отметка на карте.

geo_provider $geo_provider_id} Идентификатор картографического сервиса. Следует рассматривать это вложение только как признак того, что к сообщению прикреплена отметка на карте.

attach{$i}_product_id product_id} Идентификатор стикера.

attach{$i}_photo $owner_id}_{$item_id} Строковый идентификатор фотографии для превью ссылки (для attach{$i}_type=link).

attach{$i}_title {$title} Название ссылки (для attach{$i}_type=link).

attach{$i}_desc {$description} Описание ссылки (для attach{$i}_type=link).

attach{$i}_url {$url} URL ссылки (для attach{$i}_type=link).

emoji 1 Сообщение содержит Emoji.

from_admin {$user_id} Идентификатор администратора или редактора, отправившего сообщение. Возвращается для сообщений, отправленных от имени сообщества (только для администраторов сообщества).

source_act chat_create, chat_title_update, chat_photo_update, chat_invite_user, chat_kick_user Название сервисного действия с мультидиалогом. Возможные значения:

  • •
    chat_create — создание чата;
  • •
    chat_title_update — изменение названия чата;
  • •
    chat_photo_update — изменение фотографии чата;
  • •
    chat_invite_user — добавление собеседника в чат;
  • •
    chat_kick_user — исключение собеседника из чата.

source_mid {$user_id} Идентификатор пользователя, к которому относится сервисное действие (для source_act=chat_invite_user и source_act=chat_kick_user).

Дополнительные данные о сообщении приходят в виде отдельного объекта, который содержит поля:

title {$subject} Заголовок сообщения.

from {$user_id} Идентификатор пользователя, который отправил сообщение, если сообщение получено из беседы.

Платформы

Если в mode содержится флаг 64, то в событиях с кодом 8 (друг стал онлайн) в третьем поле будут возвращаться дополнительные данные $extra, из которых можно получить идентификатор платформы $platform_id = $extra & 0xFF ( = $extra % 256), с которой пользователь вышел в сеть. Этот идентификатор можно использовать, например, для отображения того, с мобильного ли устройства был обновлен статус онлайн (идентификаторы 1 - 5).

1 mobile Мобильная версия сайта или неопознанное мобильное приложение.

2 iphone Официальное приложение для iPhone.

3 ipad Официальное приложение для iPad.

4 android Официальное приложение для Android.

5 wphone Официальное приложение для Windows Phone.

6 windows Официальное приложение для Windows 8.

7 web Полная версия сайта или неопознанное приложение.

Примеры событий

Было удалено сообщение с message_id=123456 в диалоге с пользователем user_id=54321:

[2,123456,128,54321]

Сообщение message_id=654321 в групповом чате peer_id=2000000202 (chat_id=202) стало прочитанным:

[3,654321,1,2000000202]

В 1464950873 по Unixtime пришло сообщение message_id=654321 с текстом "Hello" (без вложений) от пользователя 123456 в групповом чате peer_id=2000000202:

[4,654321,8193,2000000202,1464950873,"Hello.",{"from":"123456 "}]

Новое сообщение от user_id=123456 с текстом "hello" и двумя вложениями (фото и аудио):

[4,2105994,561,123456,1496404246,"hello",{"title":" ... "},{"attach1_type":"photo","attach1":"123456_417336473","attach2_type":"audio","attach2":"123456_456239018"}]