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.
The Realtime Services API uses the WebSocket protocol to deliver messages in real time.
When some activity occurs in Dashly (for example, a new message in a dialog, the start of a new dialog by a user, the execution of a certain event, etc.), we send a notification (message) about it. There can be quite a lot of such messages. In order to be able to receive only the necessary messages, 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.
Connection URL is formed as follows:
wss://realtime-services.dashly.app/websocket/channel1/channel2?auth_token=XXX
wss - secure WebSocket protocol (WS secure).
You can also use (but we do not recommend) the unsecured ws protocol. realtime-services.dashly.app/websocket - base access point channel1, channel2 - channels you want to subscribe to.
You can specify up to 50 channels in one connection. tag and time parameters (see reconnection section).Like other API requests, the Realtime Services API requires authorization. The same authorization types that are available in the Web API are supported.
If the connection is successful, you will receive a 101 HTTP code in response to the request and messages will start arriving in it.
In case of unsuccessful connection, an Http response code other than 101 will be returned.
The error can also be further detailed by the first message in the socket.
| Error code | Description |
|---|---|
| 1xxx | Socket disconnection caused by connection, protocol or other "browser" reason |
| 3401 | Access token not specified, invalid, revoked, or expired |
| 3403 | The specified access token does not grant permission to receive messages from any of the requested channels |
| 3500 | Internal Server Error |
| 3503 / 503 / 3502 / 502 | The server is temporarily unavailable or overloaded. Try again after a reasonable amount of time |
| 3429 / 429 | Server request rate too high |
To monitor that the socket is working without any problems, we use special ping messages.
These messages are sent to the socket if no other messages have arrived for more than 20 seconds. If messages have arrived, ping is not sent additionally. In some cases, ping messages may arrive more frequently. We recommend monitoring the socket for messages, and reconnect if there have been no messages on the socket for more than 1-2 minutes.
In our clients and applications we show a notification "probable internet connection loss" if we haven't received any messages from the socket for 2 minutes.
Important: You should always handle ping messages correctly, even if you don't explicitly subscribe to the ping channel. We can send them without subscribing to the channel.
After successful connection, you will receive messages. All messages are wrapped in a special "envelope":
{
"id": "1234567-0",
"channel": "user_presence_changed.100",
"channels": ["user_presence_changed.100"],
"message": { ... },
"tag": "1234567-0",
"time": "Sat, 14 Nov 2015 15:51:54 GMT"
}
id: string or number - contains a unique identifier for the message.channel: string - contains the channel this message was sent to.channels: Array[strings] - contains the list of channels the message was originally sent to.message: Dict - message content.
All object ids inside the content come as strings to solve the id_as_string problemtag: string or number and time: string - needed for correct reconnection.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 |
You can't keep the connection permanently. Sometimes it's broken by the server (for example, to update or switch to a backup system), sometimes by the client (if it thinks the connection is "hung" or there was a network error, or for some other reason).
Some time will pass between the moment of disconnection and the moment of the next connection.
Messages may also arrive during this period. In order not to lose them,
the next time you connect, you need to add the GET parameters tag and time.
These parameters are taken from the last message.
For example, if you received a message with the tag and time parameters from the example above,
then the next request would be:
wss://realtime-services.dashly.app/websocket/channel1/channel2?auth_token=XXX&tag=1234567-0&time=Sat%2C%2014%20Nov%202015%2015%3A51%3A54%20GMT
Please note that the tag and time parameters must be URL-encoded.
If the connection fails, you should try again after a short timeout (20-30 seconds), so as not to create a "snowball" of requests in case of server failure.
Note: The server stores the message history for the last 3 minutes, which usually allows you to restore the connection without losses. If the connection has not received data for more than 3 minutes, we recommend requesting the necessary data using the Web API.