Skip to main content

Platform Notifications (platform/modules/system/events)

We send out both email, SMS & WhatsApp notifications. Account management notifications are generally sent via email using custom Cognito Lambdas (these lambdas publish events to the notification lambda in the system service), most other notifications are triggered by handling specific events raised throughout the platform, for example the trading events (CreateListing, SubmitBid etc).

We have created basic integrations to Courier for email and sms notifications and Twilio for WhatsApp. The intention of the notifications component is to handle routing to the correct provider based on the notification being sent, to manage WhatsApp templates and to shorten URLs as needed.

All notifications should be sent from the System > Notifications lambda, the notifications manager is not configured to allow sending from any API or other Lambda, attempts to do so will fail.

You can send a generic notification to the Lambda with the following code as an example

const notification: INotification<{ name: string; url: string }> = {
  templateId: "AccountMagicLogin",
  email: "[email protected]",
  whatsApp: true // should we send to WhatsApp, if false fallback to SMS
  phone: "+447921673665",
  pushToken: null,
  userId: 'users/1-A',
  organisationId: 'organisations/1-A',
  payload: {
    name: "Bob",
    url: "https://app.wearehectare.com/link"
  }
}

await context.events.publish(new SendNotificationEvent(context, notification))

However we would normally not send specific notifications in code we'd configure the system notifications lambda to handle an event, extract the required data for the notification from this event and send the notification.

Templates​

Templates are configured here modules/system/events/notifications/templates. Each WhatsApp template text is in this file (See Twilio section below for more into on this). We can configure channels for each template by environment (test or live).

You can also specify an array of fields in the template that have a URL, this is used to extract the URLs and shorten them.

In general the variables we send to the notifications service should be simple to use and already formatted to the users locale.

URL shortening​

We have built our own internal URL shortening service (modules/system/core/src/hurl/index.ts) this module is responsible for parsing notificatins, extracting URLs, generating short versions and tracking clicks & handling redirects of the short URLs.

We call then Hurl (Hectare URL) and theyare stored in a HUrl document in RavenDB, each Hurl documnt represents all URls in a single notifcation and is where we track clicks

Twilio​

We have a basic integrstion to Twilio for sending WhatsApp messages.

Templates are quite fiddly with WhatsApp, each template has to be approved first, so you can't just change the notification without approval first. There are many rules around the template structure we've found the following worth noting

  1. Do not end a template with a variable {{0}}
  2. Do not put 2 variables next to each other without something to delimit them, i.e. {{1}} {{2}} will fail
  3. Dont group too many variables together even if delimited, for example {{1}}, {{2}} to {{3}} on {{4}} will probably fail

Courier​

We send email via Courier. Templates are managed in Couriers dashboard https://app.courier.com/. We send the same variables to both Twilio and Courier.