Skip to main content

Notification Center

Installation​

Basic​

The configuration keys you can change are the following :

  • config :
    • nats :
      • subject : Valid Nats subject from which notifications should be fetched (eg: notifications.*)
      • addr : Endpoint of the nats server notifications should be fetched from, port included.
      • durableName : Durable name of the nats consumer. Messages on a subject are load balanced on every consumer using the same durable name.
    • synapse :
      • baseUrl : endpoint of the synapse server you want to post notifications to, scheme & port included.
      • username : Name of the account to use to post messages in synapse.
      • password : Password of the account to use to post messages in synapse.
      • skipCertCheck : Whether to skip certificate validation.
      • accessTokenLifetimeInSec : Duration of a valid synapse access token (not to confuse with OIDC access token)

Advanced​

The configuration keys you can change are the following :

  • replicaCount : The number of pods you want running
  • podAnnotations : Additional annotations to set on the pods.
  • podLabels : Additional labels to set on the pods.
  • resources :
    • limits : Limits describes the maximum amount of compute resources allowed. The kind cpu & memory are supported.
    • requests : Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. The kind cpu & memory are supported.

Usage​

Inviting the bot account​

The bot account need to be invited in the rooms where you want notifications to be sent, once done it will automatically accept and join the channel.

Writing Notifications​

The notifications should be sent to a jetstream nats as a json STRING (not avro or other specific formats). Nats header are not currently used. If the stream is not yet created when the notifier initialize, it will be created, otherwise it will be updated to match the notifier client configuration.

There are currently two fields supported in the JSON notifications :

  • roomAlias : this field should contain either the room unique ID or its alias
    • Alias are under the format : #<alias>:<matrix-server-name>
    • Unique id are under the format : !<id>:<matrix-server-name>
  • message : this contains the notification you wish to send.
    • Mentions are supported, but you need to give the bot account the permissions to use mention in the channel for this to work.

As the notifications must go through jetstream nats, you will have to respect the maximum message size configured. (default: 1 MB)

Sample Notifications​

Using the human-readable room alias (starting with #) :

{
    "roomAlias": "#test1:kosmos-matrix",
    "message": "this is a test message sent to a room by alias for user @atheaadmin:kosmos-matrix"
}

Using the room ID directly (starting with !) :

{
    "roomAlias": "!cegqmHkBxkhGiOjvIW:kosmos-matrix",
    "message": "this is a test message sent to a room by id with general mention @here"
}

Note: To get the room ID click on the 3 dot next to a channel name (Room Options), then Settings and lastly go to the Advanced tab. The id can be copy/paste from the Internal room ID field.

Debug with nats box​

In order to debug th system you may go inside the container NatsBox that is deployed inside the cluster alongside the Nats server

# adapt the container name to yours
kubectl exec -it -n kosmos-collab nats-box-85784bbcbd-pxfbs -- /bin/bash
nats pub -J notifs.debug '{"roomAlias": "#test1:kosmos-matrix","message": "this is a test message sent to a room by alias for user @atheaadmin:kosmos-matrix"}'