Realtime Services API

Realtime Services API (RTS API) — это один из наших API, который позволяет в реальном времени получать обновления, происходящие в Carrot quest. Этот API используется (в том числе) в наших официальных клиентах и приложениях.

Введение

Есть три способа подключения:

  • WebSocket (предпочтительный вариант)
  • Long polling (если не получается через WebSocket)
  • Short polling (наименее предпочтительный вариант)

Когда в Carrot quest происходит какая-то активность (например, новое сообщение в диалоге, начало нового диалога пользователем, совершение определенного события и т.д.) мы отправляем уведомление об этом (сообщение) в realtime-сервисы. Таких сообщений может быть достаточно много, поэтому они сгруппированы в каналы.

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

Мы используем Nginx Push Stream Module.

Подключение

URL для подключения формируется следующим образом:

WebSocket:

wss://realtime-services.carrotquest.io/websocket/channel1/channel2?auth_token=XXX

Long polling:

https://realtime-services.carrotquest.io/longpoll/channel1/channel2?auth_token=XXX

Short polling:

https://realtime-services.carrotquest.io/shortpoll/channel1/channel2?auth_token=XXX

На данный момент хост для подключения — realtime-services.carrotquest.io. Протоколы: ws (незашифрованный WebSocket), wss (зашифрованный WebSocket), http (незашифрованный long polling или short polling), https (зашифрованный long polling или short polling).

Далее после слеша идет способ подключения (websocket, longpoll, shortpoll). Таймаут для long poll соединения — 25 секунд.

Затем нужно указать список каналов, на которые вы хотите подписаться. Можно указать несколько каналов, разделив их слешем (но не более 50 каналов в одном соединении).

В конце нужно добавить GET-параметр auth_token. Это тот же самый токен, который используется в Web API (см. раздел авторизация). Можно добавить дополнителльные GET-параметры tag и time (см. раздел "переподключение" ниже).

Сообщения

После успешного подключения вы будете получать сообщения. Пример такого сообщения:

{
    "id": 3282,
    "channel": "user_presence_changed.100",
    "message": { ... },
    "tag": "21",
    "time": "Sat, 14 Nov 2015 15:51:54 GMT"
}

id содержит идентификатор сообщения.

channel содержит канал, в который пришло это сообщение.

message это само сообщение.

tag и time нужны для корректного переподключения (см. ниже).

Каналы

Каналы, на которые вы можете подписаться, используя Realtime Services API.

Канал Описание
ping Для контроля целостности соединения
user_presence_changed.{app_id} Изменился статус пользователя
admin_presence_changed.{app_id} Изменился статус администратора
conversation.{app_id} Начат новый диалог с пользователем
conversation.{app_id}.{user_id} Начат новый диалог с пользователем {user_id}
conversation_started_user.{app_id} Пользователь начал новый диалог
conversation_reply.{app_id} Новое сообщение в диалоге
conversation_reply.{app_id}.{user_id} Новое сообщение в диалоге с пользователем {user_id}
conversation_typing.{app_id} Кто-то печатает в диалоге
conversation_typing.{app_id}.{user_id} Кто-то печатает в диалоге с пользователем {user_id}
conversation_read.{app_id} Пользователь прочел диалог
conversation_read.{app_id}.{user_id} Пользователь {user_id} прочел диалог
conversation_assigned.{app_id} Диалог был назначен
conversation_closed.{app_id} Диалог был закрыт
conversation_tag_added.{app_id} К диалогу добавлен тег
conversation_tag_deleted.{app_id} У диалога удален тег
user_props_changed.{app_id}.{user_id} Обновились свойства пользователя {user_id}
event.{app_id}.{user_id} Пользователь {user_id} совершил событие

Переподключение

Подключение не получится держать постоянно. Для long polling и short polling переподключение — это обычное дело. Даже WebSocket-соединение не получится держать вечно. При обрыве соединения или в случае сетевых проблем нужно переподключиться заново.

С момента отключения и до момента следующего подключения пройдет некоторое время. В этот промежуток времени тоже могут прийти сообщения. Чтобы не потерять их, при следующем подключении нужно добавить GET-параметры tag и time.

При подключении по WebSocket, эти параметры берутся из последнего сообщения. При использовании схемы long polling или short polling они находятся в заголовках ETag и Last-Modified соответственно.

Например, если вы используете WebSocket и получили сообщение с параметрами tag и time из примера выше, то следующий запрос будет:

wss://realtime-services.carrotquest.io/websocket/channel1/channel2?auth_token=XXX&tag=21&time=Sat%2C%2014%20Nov%202015%2015%3A51%3A54%20GMT

Обратите внимание, что параметры tag и time должны быть URL-encoded.

Для тех, кто использует long polling или short polling:

  • Каждый запрос (кроме первого) обязательно должен включать GET-параметры tag и time от последнего сообщения. Иначе вы пропустите все самое важное, пока идет переподключение
  • Возможен случай, когда будет возвращено несколько сообщений. Тогда они будут разделены символами переноса строки (\n)
  • Если нет сообщений (или истек таймаут), то будет возвращен ответ с HTTP-статусом 304 (Not Modified)

Если подключиться не удалось, повторную попытку стоит делать, выдержав небольшой таймаут (20-30 секунд). Потому что be nice.