Notifications client

The SDK provides a Notifications client to manage and send notifications.

Note

The client variable in the following code examples refers to the ContentHubClient instance. When using the JavaScript SDK, the variable name can be chosen freely, but is also called client at instantiation in the documentation. The id argument uses 64-bit number as input.

Email templates

Mail template entities contain the templates for sending emails. The variables can be resolved at runtime.

IMailTemplateEntity is a subtype of IEntity. It provides JavaScript properties and methods for the members on the M.Mailing.Template entity definition.

The client provides extra getters for getting these mail templates, that are not available on the entities client. It allows fetching mail templates by name. However, every operation on an IEntity still applies to IMailTemplateEntity. Saving and deleting IMailTemplateEntity objects are still done through the entities client.

Getting an email template

To get an email template by ID, see the following code:

RequestResponse
import { IMailTemplateEntity } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/notifications/mail-template";

var template = await client.entities.getAsync(id) as IMailTemplateEntity;

Creating an email template

A simple Hello world template could look like this:

RequestResponse
import CultureInfo from "@sitecore/sc-contenthub-webclient-sdk/dist/culture-info";
import { IMailTemplateEntity } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/notifications/mail-template";

var enUS: CultureInfo = "en-US";

var template = await client.entityFactory.createAsync("M.Mailing.Template") as IMailTemplateEntity;
template.name = "Hello world template";
template.setSubject(enUS, "Hello there!");
template.setBody(enUS, "Hello {{Username}}!");

await client.entities.saveAsync(template);

Sending email notifications

Emails can be sent to users by username, by user ID, or by a broadcast. There are three respective overloads to the SendEmailNotificationAsync. It accepts the following input:

  • MailRequestById - for specifying users by ID.

  • MailRequestByUsername - for specifying users by username.

  • MailRequestBroadcast - sends to all users.

Suppose we would like to send an email broadcast using the template we just created:

RequestResponse
import { MailRequestBroadcast } from "@sitecore/sc-contenthub-webclient-sdk/dist/models/notifications/mail-request-broadcast";

var request = new MailRequestBroadcast();
request.mailTemplateName = "Hello world template";
request.variables["Username"] = "world";

await client.notifications.sendEmailNotificationAsync(request);

This will send an email to everyone containing Hello world!.

Sending real-time notifications

Real-time notifications can be sent to users by username, by user ID, or by a broadcast. There are three respective overloads to the SendRealTimeNotifcationAsync. It accepts the following input:

  • RealtimeRequestById - for specifying users by ID.

  • RealtimeRequestByUsername - for specifying users by username.

  • RealtimeRequestBroadcast - sends to all users.

Suppose we would like to send a real-time notification to the DemoUser:

RequestResponse
import { RealtimeRequestByUsername } from "@sitecore/sc-contenthub-webclient-sdk/dist/models/notifications/realtime-request-by-username";

var request = new RealtimeRequestByUsername();
request.recipients.push("DemoUser");
request.setBody("Your description");
request.setIcon("https://example.com/image.png");

await client.notifications.sendRealTimeNotificationAsync(request);

The link is opened when the user clicks on the notification.

This real-time request interface is built on the standard notifications API. This API uses an options object that contains all the notification information. This object is directly passed from the IRealtimeRequest.Options property. Some helper methods have been provided to help configure this options object, for example the body and the icon of the notification.

Sending account confirmation emails

Important

For SendConfirmationEmailAsync to work, you need to set EnableConfirmationMail to true in the settings.

Sending confirmation emails to users can be done using IDs or usernames:

RequestResponse
await client.notifications.sendConfirmationEmailAsync(["DemoUser"]);

This will send an email to the specified user containing a secure link to activate their account.

Do you have some feedback for us?

If you have suggestions for improving this article,