Realtime Services API (RTS API) — это один из наших API, который позволяет в реальном времени получать обновления, происходящие в Carrot quest. Этот API используется (в том числе) в наших официальных клиентах и приложениях.
Есть три способа подключения:
Когда в 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} | Изменился статус пользователя |
| conversation.{app_id} | Начат новый диалог с пользователем |
| conversation.{app_id}.{user_id} | Начат новый диалог с пользователем |
| conversation_started_user.{app_id} | Пользователь начал новый диалог |
| conversation_reply.{app_id} | Новое сообщение в диалоге |
| conversation_reply.{app_id}.{user_id} | Новое сообщение в диалоге с пользователем |
| conversation_typing.{app_id} | Кто-то печатает в диалоге |
| conversation_typing.{app_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} | Обновились свойства пользователя |
| 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:
tag и time от последнего сообщения.
Иначе вы пропустите все самое важное, пока идет переподключение\n)Если подключиться не удалось, повторную попытку стоит делать, выдержав небольшой таймаут (20-30 секунд). Потому что be nice.