This document describes how to get real-time notifications of changes regarding specific topics. The two main areas which will be described are the process of clients subscribing to change notifications, and the propagation of notifications to clients.
Whenever notifications are talked about in this document, we’re referring to these change notifications (not to be confused with alerts, which are the user-visible notifications represented with a bell and a little red counter in the UI).
In order to receive any change notifications, a client needs to create a persistent socket connection to the Speakap emitter. To do so, clients should connect using Socket.io v1.x to https://n2.speakap.io/. Once connected, clients may subscribe to one or more channels, after which they will receive all change notifications relevant to those channels.
In order to receive any kind of change notifications, clients need to subscribe to one or more notification channels. This is done by sending a simple subscribe message. The command to subscribe will look something like this:
socket.emit("subscribe", {
"channel": "channel_id",
"accessToken": "..."
});
The given channel may optionally be a space-separated list of channel IDs.
The access token given is the same token as used for communicating with the REST API. Please note the access token is only verified at the moment of subscription, so even if the token expires, the subscription will remain valid.
Once subscribed, the client will receive all change notifications related to the specified channel(s). If desired, a client can also unsubscribe from a channel:
socket.emit("unsubscribe", {
"channel": "channel_id"
});
Clients may subscribe to new channels and unsubscribe from subscribed channels at any time for as long as they remain connected.
When the connection from a client to the Speakap emitter is disconnected, the client is automatically unsubscribed from all its subscribed channels. This means if the disconnection was involuntary (network problems, server crash, ...), the client will have the responsibility of reconnecting to the server, subscribing to all relevant channels again and checking if no changes went undetected[1].
Clients may be subscribed to a wide variety of notification channels, many of which have a direct relation to the “view” the client may be displaying. It is discouraged for clients to be subscribed to channels that have no relevance to any view visible by the user.
Each header in this section relates to a specific channel.
Channel ID: config
This channel is used for propagating configuration changes.
| Key | Value | Description |
|---|---|---|
| type | “servers_busy” | This notification is sent to inform clients the Speakap servers are under heavy load. If the client performs any kind of polling, pre-fetching or other kinds of tasks that may incur heavy overhead, they are encouraged to pause or scale back or these activities until the load has returned to normal. |
| type | “servers_normal” | This notification is sent to inform client the load on the Speakap server has returned to normal. |
Channel ID: network_timeline:<networkEID>
This channel is used for propagating changes to the generic network timeline. Please note that the personalized network timeline users see is a combination of this generic network timeline merged with the individual group timelines of the groups s/he is a member of.
| Key | Type | Description |
|---|---|---|
| event | “bubble” | Indicates a message has bubbled (an existing update is moved back to the top of the timeline because a comment arrived). |
| event | “create” | Indicates a new message has been posted. |
| event | “delete” | Indicates a message has been deleted. |
| event | “like” | Indicates a message has been liked. |
| event | “unlike” | Indicates a message has been unliked. |
| liker | EID | EID of the user who liked or unliked message. |
| message | EID | EID of the message that was posted to the timeline. |
| author | EID | EID of the user who authored the posted message. |
| parent | EID | EID of the parent message to which the posted message was added. This property is optional and only relevant for comments. |
| firstCommentByAuthor | boolean | Indicates whether this is the first comment on the parent message by the author. This property is optional and only relevant for “create” events for comments. |
| deletedBy | string | “author” or “admin” depending on who deleted the message. This property is optional and only relevant for “delete” events for comments. |
Channel ID: user_timeline:<userEID>:<networkEID>
This channel is used for propagating changes to a user profile timeline.
| Key | Type | Description |
|---|---|---|
| event | “bubble” | Indicates a message has bubbled (an existing update is moved back to the top of the timeline because a comment arrived). |
| event | “create” | Indicates a new message has been posted. |
| event | “delete” | Indicates a message has been deleted. |
| message | EID | EID of the message that was posted to the timeline. |
| author | EID | EID of the user who authored the posted message. |
| parent | EID | EID of the parent message to which the posted message was added. This property is optional and only relevant for comments. |
| firstCommentByAuthor | boolean | Indicates whether this is the first comment on the parent message by the author. This property is optional and only relevant for “create” events for comments. |
| deletedBy | string | “author” or “admin” depending on who deleted the message. This property is optional and only relevant for “delete” events for comments. |
Channel ID: group_timeline:<groupEID>:<networkEID>
This channel is used for propagating changes to a group profile timeline.
| Key | Type | Description |
|---|---|---|
| event | “bubble” | Indicates a message has bubbled (an existing update is moved back to the top of the timeline because a comment arrived). |
| event | “create” | Indicates a new message has been posted. |
| event | “delete” | Indicates a message has been deleted. |
| message | EID | EID of the message that was posted to the timeline. |
| author | EID | EID of the user who authored the posted message. |
| parent | EID | EID of the parent message to which the posted message was added. This property is optional and only relevant for comments. |
| firstCommentByAuthor | boolean | Indicates whether this is the first comment on the parent message by the author. This property is optional and only relevant for “create” events for comments. |
| deletedBy | string | “author” or “admin” depending on who deleted the message. This property is optional and only relevant for “delete” events for comments. |
Channel ID: message:<messageEID>:<networkEID>
This channel is used for propagating changes to a specific message, including comments added to that message.
| Key | Type | Description |
|---|---|---|
| event | “bubble” | Indicates a message has bubbled (an existing update is moved back to the top of the timeline because a comment arrived). |
| event | “create” | Indicates a new message has been posted. |
| event | “delete” | Indicates a message has been deleted. |
| message | EID | EID of the message itself or that of a comment added to it. |
| author | EID | EID of the user who authored the message. |
| parent | EID | EID of the parent message to which the posted message was added. This property is optional and only relevant for comments. |
| firstCommentByAuthor | boolean | Indicates whether this is the first comment on the parent message by the author. This property is optional and only relevant for “create” events for comments. |
| deletedBy | string | “author” or “admin” depending on who deleted the message. This property is optional and only relevant for “delete” events for comments. |
Channel ID: message_readers:<messageEID>:<networkEID>
This channel is used for propagating who read a specific message. You may only subscribe to this channel if you have the “view_readers” permission for the specified message. This is only applicable for news items.
| Key | Type | Description |
|---|---|---|
| event | “read” | Indicates a user has read a message. |
| message | EID | EID of the message itself. |
| reader | EID | EID of the user who read the message. |
Channel ID: my_memberships:<userEID>:<networkEID>
This channel is used for propagating all changes related to the user’s memberships.
| Key | Type | Description |
|---|---|---|
| event | “create” | Indicates a membership has been created for the user. |
| event | “delete” | Indicates a membership of the user has been deleted. |
| event | “role_change” | Indicates the role of a membership of the user has been changed. |
| membership | EID | EID of the membership object. |
| rev | string | Type of the object related to the membership (either “group” or “network”). |
| group | EID | Group related to the membership. This property is optional and only relevant if rev is “group”. |
| role | string | The user’s new role. This property is optional and not relevant for a “delete” event. |
| oldRole | string | The user’s old role. This property is optional and not relevant for a “create” event. |
Channel ID: group_memberships:<userEID>:<networkEID>
This channel is used for propagating changes related to a group’s memberships.
Note this does not include changes to memberships regarding invitations and membership requests. Those are only accessible to group admins and require a subscription to the group admin memberships channel.
| Key | Type | Description |
|---|---|---|
| event | “create” | Indicates a membership has been created in the group. |
| event | “delete” | Indicates a membership has been deleted in the group. |
| event | “role_change” | Indicates the role of a membership in the group has been changed. |
| membership | EID | EID of the membership object. |
| rev | “group” | Type of the object related to the membership (always “group”). |
| group | EID | The membership group. |
| role | string | The membership user’s new role. This property is optional and not relevant for a “delete” event. |
| oldRole | string | The membership user’s old role. This property is optional and not relevant for a “create” event. |
Channel ID: group_admin_memberships:<userEID>:<networkEID>
This channel is used for propagating all changes related to a group’s memberships.
Note this channel is a superset of the group memberships channel, but also includes changes to memberships regarding invitations and membership requests.
| Key | Type | Description |
|---|---|---|
| event | “create” | Indicates a membership has been created in the group. |
| event | “delete” | Indicates a membership has been deleted in the group. |
| event | “role_change” | Indicates the role of a membership in the group has been changed. |
| membership | EID | EID of the membership object. |
| rev | “group” | Type of the object related to the membership (always “group”). |
| group | EID | The membership group. |
| role | string | The membership user’s new role. This property is optional and not relevant for a “delete” event. |
| oldRole | string | The membership user’s old role. This property is optional and not relevant for a “create” event. |
Channel ID: alerts:<globalUserEID>
This channel is used for propagating notifications when an alert is received, revoked or has been read.
Please note this channel subscribes to notifications relevant to a user across all the networks he or she is a member of. For this reason, the channel ID uses the global user EID (which can be retrieved using the WhoAmI resource).
| Key | Type / Value | Description |
|---|---|---|
| event | “create” | Indicates a new alert has been created and received by the user. |
| event | “delete” | Indicates an alert has been revoked and deleted for the user. |
| event | “read” | Indicates an alert has been read by the user. |
| alert | EID | EID of the alert that has been created, deleted or read. In the case of a “read” event, this property is optional. If omitted, the event applies to all of the user’s alerts of the given category and in the given network. |
| network | EID | EID of the network in which the alert was created, deleted or read. |
| category | “user” | The alert is of the “user” type. These are all alerts labelled as “Notifications” in the web UI. |
| category | “admin” | The alert is of the “admin” type. These are all alerts labelled as “Admin Tasks” in the web UI. |
| numUnreadAlerts | integer | If the category is “user”, this property contains the new value of the unread alerts counter. |
| numAdminAlerts | integer | If the category is “admin”, this property contains the new value of the admin tasks counter. |
Channel ID: messages:<globalUserEID>
This channel is used for propagating notifications when a private message has been received, deleted or read.
Please note this channel subscribes to notifications relevant to a user across all the networks he or she is a member of. For this reason, the channel ID uses the global user EID (which can be retrieved using the WhoAmI resource).
| Key | Type / Value | Description |
|---|---|---|
| event | “create” | Indicates a new private message has been created and received by the user. |
| event | “delete” | Indicates a private message has been deleted. |
| event | “leave” | Indicates a conversation has been left. |
| event | “read” | Indicates a private message has been read by the user. |
| message | EID | EID of the private message that has been created, deleted or read. In the case of a “read” event, this property is optional. If omitted, the event applies to all of the private messages in the given conversation. |
| messageType | string | Type of the private message that has been created. |
| conversation | EID | EID of the conversation to which the private message belongs or belonged. |
| author | EID | EID of the user who authored the private message. This property is optional and only relevant in case of a “create” event. |
| network | EID | EID of the network in which the private message was created, deleted or read. |
| numUnreadConversations | integer | This property contains the new value of the unread conversations counter. |
Channel ID: news:<globalUserEID>
This channel is used for propagating notifications when a news item has been published, deleted or read.
Please note this channel subscribes to notifications relevant to a user across all the networks he or she is a member of. For this reason, the channel ID uses the global user EID (which can be retrieved using the WhoAmI resource).
| Key | Type / Value | Description |
|---|---|---|
| event | “create” | Indicates a news item has been created and become visible to the user. |
| event | “publish” | Indicates a news item has been published. |
| event | “delete” | Indicates a news item has been deleted. |
| event | “read” | Indicates a news item has been read by the user. |
| message | EID | EID of the news item that has been created, published, deleted or read. |
| author | EID | EID of the user who authored the news item. This property is optional and only relevant in case of a “create” or “publish” event. |
| network | EID | EID of the network in which the news item was created, published, deleted or read. |
| numUnreadNewsItems | integer | This property contains the new value of the unread news items counter. |
Note that depending on whether the user has permissions to author and publish news item he or she may or may not receive “create” events. On the other hand, “publish” events are received by all users in the network.
| [1] | Detection of changes that occurred while the client was not subscribed should be done through API calls because the Speakap emitter will forget about any notifications as soon as they’ve been propagated. |