Realtime Services API

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.

Introduction

There are 3 connection methods:

  • WebSocket (recommended)
  • Long polling (can’t connect through WebSocket)
  • Short polling (not recommended)

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

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).

Messages

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

Channels you can subscribe to, using Realtime Services API

Channel Description
ping For connection integrity monitoring
user_presence_changed.{app_id} User status changed
admin_presence_changed.{app_id} Admin 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

Reconnection

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:

  • Each request (excluding the first) must have tag and time GET-parameters from the last message. Else you’ll be missing something important during reconnection.
  • It is possible that several messages will be received simultaneously. Then they will be separated by the line break characters (\n)
  • If there are no messages (or timeout is off) answer with HTTP-status 304 (Not Modified) will be returned.

In case connection fails, a pause should be taken before retrying to establish connection (20-30 seconds). Be nice.