Apps
Notifications are transactional messages designed to keep customers and admins informed about events occurring within the system. Email notifications are supported by default through Sendgrid. Additional methods such as SMS can be implemented by Apps.
There are built-in notifications for common use cases, and the platform offers flexibility in configuring notifications, including templates, event conditions, and default contact and delivery settings.
Notification templates are used to render a message for any medium such as email. Templates support Liquid syntax out of the box. Liquid allows you to include dynamic content, use control structures, and access various data points related to your application.
Notifications can be triggered by any model event, whether it's a standard event like a record being updated, or a custom event specific to your application. Additionally, custom conditions can define a set of criteria that must be met for a notification to be sent.
Swell supports multiple languages and currencies in notifications, allowing you to provide a tailored experience for users around the world. Using the Swell dashboard, a merchant can manage localized content, subject lines, and other elements depending on the customer’s language or currency preferences, ensuring a personalized and relevant communication experience for each recipient.
Merchants can test their notification templates directly from the Swell dashboard, while developers have the option to send test notifications using the backend API. In addition, Swell allows you to configure sample data that is used when testing notifications, while live data from actual events is utilized when the system automatically triggers notifications. This approach enables you to ensure that your templates work as expected with both test and live data.
API endpoints provide developers with the ability to interact with the notification system programmatically. Developers can create notifications directly, which are then processed asynchronously, as well as retrieve and analyze notification records for various use cases and integrations. In addition, developers can use the API to send live and test notifications. The $notify operator allows you to force-send notifications for any given record.
The following table outlines the attributes Swell supports for use with notifications.
| Attribute | Description |
| collection | The database collection to trigger notifications relative on platform-level events, for example, carts. |
| label | A label to identify this notification. Not visible to customers. |
| description | A longer description of this notification. Not visible to customers. |
| method | The method of delivering a notification. email is the only currently supported method by default. Custom methods can be implemented by hooking into the notification.send event with functions. |
| subject | A simple string template supporting Liquid syntax, to act as the notification subject. |
| contact | Path of a field relative to the collection model. For example, in Carts, the path account.email will traverse the record relationship to an account and use the customer’s email as the recipient address. |
| conditions | An object using standard operators to filter function invocation based on specific properties in a request. |
| event | A model event to trigger this notification. If not specified, the notification will be triggered by default when any record is created or updated in the respective collection which also matches conditions. |
| new | Boolean value indicating whether this notification should only be sent when a record is newly created. In that case, further record updates will not trigger this notification. |
| repeat | Boolean value indicating whether this notification should be sent each time the event occurs. Otherwise, a notification is only sent the first time an event occurs. |
| admin | Boolean value indicating this notification is intended for merchant admins, and therefore the contact property will be ignored in favor of sending to all merchants admins that are opted-in to platform notifications. |
Use notifications to set up automated communications with merchant admins and end users. Email notifications are supposed by default, backed by Sendgrid, while it’s possible to implement new notification mediums such as SMS using your own app functions.
Here’s an example of a simple notification configuration:
{
"collection": "carts",
"label": "Quote Receipt",
"description": "Send an email to users confirming receipt of their quote request",
"method": "email",
"subject": "Your request for quote has been received ({{ number }})",
"contact": "account.email",
"event": "quote_submitted"
}
In the above example, we’ve configured a notification to be sent to a customer’s [account.email](<http://account.email>) address when a custom event quote_submitted is fired. The conditions for this custom event would be configured on the carts model.
It’s also possible to define custom conditions for a notification, in addition to, or exclusive of a model event:
{
...
"event": "quote_submitted",
"conditions": {
"finalized": true
}
}
The next step is to add a template to constitute the body of the notification email in this case. Here’s an example of a simple email template, using Liquid syntax:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ subject }}</title>
</head>
<body>
<p>Your quote has been received ...</p>
<p>Quote total: {{ grand_total | currency }}</p>
...
</body>
</html>