Realtime Services API (RTS API) is one of our APIs that allows you to receive real-time updates in the Dashly. This API is used (including) in our official clients and applications.
There are 3 connection methods:
When there is any activity in Dashly (for example, a new message in a conversation, a user begins new conversation, commission of a certain event, etc.), we send a notification about this (message) into the real-time services. Those messages can be numerous, so they are grouped into channels.
You can specify channels you'd like to listen/ For example, you can listen only to channel with notifications about new chat mesages.
We're using Nginx Push Stream Module.
Connection URL is formed as follows:
WebSocket:
wss://realtime-services.dashly.app/websocket/channel1/channel2?auth_token=XXX
Long polling:
https://realtime-services.dashly.app/longpoll/channel1/channel2?auth_token=XXX
Short polling:
https://realtime-services.dashly.app/shortpoll/channel1/channel2?auth_token=XXX
At the moment connection host is realtime-services.dashly.app.
Protocols: ws(unencrypted WebSocket), wss (encrypted WebSocket),
http (unencrypted long polling or short polling), https (encrypted long polling or short polling).
Next. Connection method after slash (websocket, longpoll, shortpoll). Long poll connection timeout — 25 seconds.
After that a list of channels you want to subscribe to should be specified. Several channels can be specified, separated with slash (up to 50 in one connection).
GET-parameter auth_token should be added in the end. The same token is used in Web API
(see authorization)
Optional GET-parameters tag and time can be added (see “reconnection” lower).
You will start receiving messages after successful connection. Example:
{
"id": 3282,
"channel": "user_presence_changed.100",
"message": { ... },
"tag": "21",
"time": "Sat, 14 Nov 2015 15:51:54 GMT"
}
id Contains message identificator.
channel Contains channel this message was received into.
message — the message itself.
tag and time Required for correct reconnection (described further on).
Channels you can subscribe to, using Realtime Services API
| Channel | Description |
|---|---|
| ping | For connection integrity monitoring |
| user_presence_changed.{app_id} | User status changed |
| conversation.{app_id} | A new conversation with a user started |
| conversation.{app_id}.{user_id} | A new conversation with a user {user_id} started |
| conversation_started_user.{app_id} | A user started a new conversation |
| conversation_reply.{app_id} | New message in a conversation |
| conversation_reply.{app_id}.{user_id} | New message in a conversation with user {user_id} |
| conversation_typing.{app_id} | Someone is typing |
| conversation_typing.{app_id}.{user_id} | Someone is typing in a conversation with user {user_id} |
| conversation_read.{app_id} | User read a conversation |
| conversation_read.{app_id}.{user_id} | User {user_id} read a conversation |
| conversation_assigned.{app_id} | Conversation was assigned |
| conversation_closed.{app_id} | Conversation was closed |
| conversation_tag_added.{app_id} | A tag was added to a conversation |
| conversation_tag_deleted.{app_id} | A tag was removed from a conversation |
| user_props_changed.{app_id}.{user_id} | User’s {user_id} properties were altered |
| event.{app_id}.{user_id} | User {user_id} performed an event |
Connection can not be maintained permanently. Reconnection is common for long polling and short polling. Even WebSocket-connection can not be maintained permanently. When connection is lost or there is a network error, you’ll have to reconnect.
Some time will pass from the moment connection is lost to the moment connection is re-established.
New messages might be received during this period. Add tag and time GET-parameters not to lose those messages.
In WebSocket connection, these parameters are taken from the last message.
They are contained in ETag and Last-Modified titles when long polling or short polling is being used.
For example, you’re using WebSocket and have got a message with tag and time parameters from the previous example, then the next request will be:
wss://realtime-services.dashly.app/websocket/channel1/channel2?auth_token=XXX&tag=21&time=Sat%2C%2014%20Nov%202015%2015%3A51%3A54%20GMT
Pay attention, that tag and time parameters should be URL-encoded.
For those using long polling or short polling:
tag and time GET-parameters from the last message.
Else you’ll be missing something important during reconnection.\n)In case connection fails, a pause should be taken before retrying to establish connection (20-30 seconds). Be nice.