Server Messages
Server messages can be sent unsolicited or in response to a client message. If a server message is sent in response to a client message, and the client message had an “id” field, the server message will be sent with an optional “reply-to” field that will contain the message identifier for the client message it is in response to.
Client Message Acknowledge
Type: ack
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
id | String | Optional: if the client message had an id field, this field will contain the same text. |
reply-to | String | Optional: if the client message this message is sent in response to had an id field, this field will contain the id. |
status | Boolean | Whether the message was handled correctly or generated an error. |
This message is sent after handling each client message. These are sent in the exact order the client messages have been received and each ACK message pertains to one client message received by the server.
Delivery Notification
Type: delivery
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
message-id | String | The identifier of the message this delivery notification pertains to |
status | String | The status of the message delivery |
The delivery notification message must be sent by the server when a direct message or a channel message sent by the subscriber changes into one of the following statuses:
| Status Text | Description |
|---|---|
stored | The message has been received by the server and stored for future delivery. |
received | A direct message has been sent to the recipient’s application. |
displayed | A direct message has been displayed visibly on the recipient’s screen. This could be in the form of a notification. |
read | A direct message has been fully displayed by an application’s chat or channel view, allowing the recipient to read the full text. |
Channel Invitation
Type: invitation
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel the subscriber is invited to |
name | String | Description of the channel to show to subscribers |
attributes | Object | List of channel properties |
administrator | true/false | Whether the subscriber is being invited to be an administrator or not |
The channel invitation message is sent from the server when a subscriber with administration permissions in a channel invites a user to that channel. The “administrator” flag is used to notify the application that the subscriber can now perform administrative operations.
Channel Unsubscription
Type: unsubscription
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel the subscriber was removed from. |
subscriber | Object | The subscriber that was removed from the channel. See the Channel Subscriber Model below for the field details. |
This message is sent from the server when a subscribe is removed from a channel.
Channel List
Type: channel-list
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channels | Array<ChannelMembership> | List of channel membership report. See the Channel Membership model below for the field details. |
The channel list message is sent from the server as a response to the List Channels message and contains a list of all channels the user is currently a subscriber of and whether the user is an administrator of the channel or not.
Channel Directory
Type: directory
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel this directory lists |
subscribers | Array<ChannelSubscriber> | List of subscribers in the channel. See the Channel Subscriber Model below for the field details. |
The directory message is sent to the application in response to a list channel subscribers message. The message includes a list of all subscribers registered in the channel and an indication of their status (to save the application the need to send an availability check message). The “status” field must contain one of the values listed for the announce message, or the value “offline” specifying that that subscriber has not issued an “Announce Availability” message since their last disconnect or since their last “Unannounce” message.
Channel Member Status Notification
Type: member-status
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel this notification comes from |
subscriber | ChannelSubscriber | Subscriber object whose status has changed. See the Channel Subscriber Model below for the field details. |
The member status message is sent to the user agent application when the status of another subscriber in a channel this subscriber is a member of, has changed.
Message
Type: message
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel this message was sent in. |
message-id | String | A globally unique identifier of the message that was sent. |
date | String | ISO-8601UTC formatted time when the message was sent. |
text | String | The content of the channel message. |
attributes | Objects | List of message properties. |
The “channel message” message is sent by the server when another subscriber has sent a message to a channel this subscriber is subscribed to.
Archive Retrieval
Type: archive
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel a an archive retrieval request was received for. |
count | Number | The number of archived messages retrieved |
earliest | String | ISO8601 formatted time for the earliest time that was scanned in the archive (may be earlier than the earliest message found) |
latest | String | ISO8601 formatted time for the latest time that was scanned in the archive (may be later than the latest message found) |
The “Archive Retrieval” message is sent by the server in response to a valid “Retrieve Messages From Archive” message. It contains a count of how many messages were actually retrieved from the archive, that the application is expected to then receive. This message will be followed by zero or more server messages (as per the “count” field in this message), that will be identified by carrying a “reply-to” header identical to the “reply-to” header in this message.
The time stamps sent in this message can have times later than the last message delivered in the archive retrieval transaction, or later than the last message retrieval transaction - often when the server generated less than the requested number of messages (as reported by the “count” field) - the server scans the archive backwards and may give up on fulfilling the full request, if there is a large gap between messages. If the client wishes to try again, the client may send another Retrieve Messages From Archive request with the “earliest” value (or “latest” as the case may be) from this message set as the “time” field - to ask for another try, starting from where the server last stopped.
Notes
- See RFC 6750
- See RFC 7159 section 4