Change Notifications

Introduction

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

Overview

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 v.9 to https://n.speakap.io/. Once connected, clients may subscribe to one or more channels, after which they will receive all change notifications relevant to those channels.

Subscribing

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

Channels

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.

Config

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.

Network timeline

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.

User timeline

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.

Group timeline

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.

Message

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.

My memberships

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.

Group memberships

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.

Group admin memberships

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.

Alerts

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.

Messages

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.

News

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.