Client Messages
Announce Availability
Description
The announce message may be sent by a client to publish the user’s availability for messaging operations. This message is not required to be sent immediately when connecting - after a client connects to the server and as long as they did not send an announce message, they are considered to be “invisible”.
Message Content Description
| Field Name | JSON Type | Description |
|---|---|---|
status | String | Description of the user’s status. Can be any text, which can be either shown to the user’s correspondents or be interpreted by the UA according to UA specific logic. |
availability | String | One of the valid subscriber availability statuses prescribed in the protocol. |
attributes | Object | List of metadata properties to set for the current subscriber. |
Availability Status Values
Fields:
| Value | Description |
|---|---|
invisible | The subscriber is online but is not shown to be online to other subscribers. |
available | The subscriber is fully available for messaging. |
dnd | The subscriber is in “do not disturb” mode (notifications will likely be silenced and calls rejected - depending on UA implementation). |
busy | The subscriber is in “busy” mode (notifications will likely be shown in diminished visibility and calls rejected - depending on UA implementation). |
Unannounce
Type: unannounce
Fields: This message requires no additional fields.
The unannounce message is the reverse of the announce message. When it is sent, the client becomes “invisible”, as if they aren’t actually connected.
Create Channel
Type: create-channel
Fields: This message requires no additional fields
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
name | String | Description of the channel to show to subscribers |
invite-token | String | (Optional) Unique invitation token for the channel |
attributes | Object | List of channel properties to set on the channel |
Required Response: Channel Invitation
The create channel message is sent by the application when it wants to create a new multi-subscriber communication channel. The server will then create such a channel and invite the creator as the administrator of the channel, after which the application can use additional messages to customize and administer the new channel. If the optional “invite-token” field is specified and is not empty, the server will first check if a channel with the specified invitation token already exists and if so will not create the channel and instead will invite the sender as a non-administrator user to the existing channel.
Update Channel
Type: update-channel
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to update |
name | String | Description of the channel to show to subscribers |
attributes | Object | List of channel properties to set on the channel |
Required Response: channel invitation
The update channel message can be sent by a channel administrator to update channel details. Whenever a channel is updated, either by an administrator or by a server, a new channel invitation message is sent to all members of the channel with the updated details. The server may ignore the update channel message if the sending subscriber is not an administrator of the specified channel.
Re-invite To All Channels
Type: reinvite-channels
Fields: This message requires no additional fields
The re-invite to all channels message may be sent by the application to get an update on all channels that the subscriber is a member of. When the server receives this message, it will send back a channel invitation message for each channel the subscriber is a member of. In the case that the subscriber is not a member of any channel, no channel invitation messages will be received from the server.
List Channels
Type: list-channels
Fields: This message requires no additional fields
The list channels message may be sent by the application to retrieve a list of all channels that the subscriber is a member of. When the server receives a list channels message, it will send back a channel list response containing the channel ID and administrator status of the subscriber for each of the channels the subscriber is a member of.
List Channel Subscribers
Type: list-subscribers
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to get a directory of |
Required Response: Channel Directory
The list channel subscribers message may be sent by the application to get a current directory of subscribers in a channel the current subscriber is a member of. When receiving this message the server must reply with a channel directory message detailing all current subscribers in the channel. The server may ignore the list channel subscribers message if the channel identification is not known to the server, or the sending subscriber is not a member of the channel.
Invite To Channel
Type: invite
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to invite the subscriber to |
recipient | String | The identity of the subscriber that should receive the invitation |
administrator | true/false | Whether to grant the recipient administrative rights in the channel |
The invite message may be sent by an application to add another subscriber to a channel that they are an administrator of. As a result of this message the server will send a channel invitation message to the subscriber specified as a recipient. If the sending subscriber is not an administrator of the specified channel, or if the recipient address is not known to the server, the message will be ignored.
Kick From Channel
Type: kick
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to remove the subscriber from |
recipient | String | The identity of the subscriber that should be removed from the channel |
The kick message may be sent by an application to remove a subscriber from a channel this subscriber is subscribed to.
A subscriber may use the kick message with their own identification as the recipient address to leave a channel they are subscribed to, in which case the application should expect a Channel Unsubscription message as a response.
When the recipient address is of another user, the server must verify that the subscriber issuing the kick message is listed as an administrator of the channel, and must ignore the message if that is not the case. After an administrator has sent a Kick From Channel Message, the kicked subscriber, as well as all remaining subscribers (including the kicking administrator) will receive a Channel Unsubscription message with the details of the kicked subscriber.
If the last administrator is leaving an existing channel, and if any non-administrator subscribers are left in the channel, one of the existing subscribes will be promoted to an administrator and a Channel Member Status Notification will be sent to the channel - notifying everyone of the new administrator. If no subscribers are left in the channel, the channel will be removed. The server may ignore any message where the channel identification or the recipient address is not known to the server.
Message
Type: message
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to send a message to |
message-id | String | A globally unique identifier of the message to be sent |
text | String | The content of the channel message |
attributes | Objects | List of message properties |
Required Response: Delivery Notification
The message to channel message may be sent by an application to distribute a message to all subscribers to a channel. The message will be stored and then forwarded to all other subscribers as a message of type “message”. The server must immediately respond with a delivery notification containing the status “stored”. It is the responsibility of the application to generate a unique message identifier, otherwise they may receive delivery notifications meant for other messages. The server may ignore messages sent by subscribers who are not members of the specified channel, where the message identifier is null or empty, or where the text is null.
Message Status Update
Type: message-status
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | The channel identification of the channel where this message was originally sent |
message-id | String | The identifier of the message this delivery notification pertains to |
status | String | The status of the message display |
An application must send a message status update message when it displayed a direct message on the screen. The status must be one of “displayed” if the message was shown not in a full message view (i.e. in a notification or a similar manner) or “read” if the message has been displayed fully, allowing the user to read it completely. After receiving the message the server will send a delivery notification message to all other subscribers in the channel. The server may ignore message status updates that have an invalid message identifier, an invalid channel identifier, a channel identifier the sender is not a member of, or with an invalid status field.
Retrieve Messages From Archive
Type: retrieve
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel to retrieve messages from |
time | String | ISO-8601 UTC formatted timestamp from which to start retrieving. For example "2019-06-07T09:42:52Z" |
direction | "asc"/"desc" | Whether to retrieve messages in ascending date order (towards the future) or descending (towards the past) |
count | number | Maximum number of messages to retrieve |
Required Response: message
Ask the server to retrieve past messages from the archive. As a response the server will send the “Archive Retrieval” message followed by zero or more “message” messages for each message retrieved from the archive. The user application should be able to identify such messages according to their timestamps and their “reply-to” message identifiers.
The “count” field may specify a number as high as 100. If the count specified is larger than 100, the server may assume the “count” sent was 100 and not retrieve any more messages.
Notes
- See RFC 6750
- See RFC 7159 section 4