How to Create a Notification Provider
In this document, you’ll learn how to create a notification provider in the Medusa backend and the methods you must implement in it. Learn more about the notification architecture in this documentation
Overview
Before creating a Notification Provider, install an event bus module.
A Notification Provider is a provider that handles sending and resending of notifications.
To create a Notification Provider, create a TypeScript or JavaScript file in src/services
. The name of the file is the name of the provider
(for example, sendgrid.ts
). The file must export a class that extends the AbstractNotificationService
class imported from @medusajs/medusa
.
For example, create the file src/services/email-sender.ts
with the following content:
import { AbstractNotificationService } from "@medusajs/medusa"
import { EntityManager } from "typeorm"
class EmailSenderService extends AbstractNotificationService {
protected manager_: EntityManager
protected transactionManager_: EntityManager
sendNotification(
event: string,
data: unknown,
attachmentGenerator: unknown
): Promise<{
to: string;
status: string;
data: Record<string, unknown>;
}> {
throw new Error("Method not implemented.")
}
resendNotification(
notification: unknown,
config: unknown,
attachmentGenerator: unknown
): Promise<{
to: string;
status: string;
data: Record<string, unknown>;
}> {
throw new Error("Method not implemented.")
}
}
export default EmailSenderService
Identifier Property
The NotificationProvider
entity has 2 properties: identifier
and is_installed
. The value of the identifier
property in the notification provider
class is used when the Notification Provider is created in the database.
The value of this property is also used later when you want to subscribe the Notification Provider to events in a Loader.
For example:
constructor
You can use the constructor
of your notification provider to access the different services in Medusa through dependency injection.
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
Additionally, if you’re creating your notification provider as an external plugin to be installed on any Medusa backend and you want to access the options added for the plugin, you can access it in the constructor.
Example
// ...
import { AbstractNotificationService, OrderService } from "@medusajs/medusa"
import { EntityManager } from "typeorm"
class EmailSenderService extends AbstractNotificationService {
// ...
protected orderService: OrderService
constructor(container, options) {
super(container)
// you can access options here in case you're
// using a plugin
this.orderService = container.orderService
// you can also initialize a client that
// communicates with a third-party service.
this.client = new Client(options)
}
// ...
}
export default EmailSenderService
Parameters
container
Record<string, unknown>RequiredMedusaContainer
that allows you to access other resources, such as services, in your Medusa backend.config
Record<string, unknown>Methods
sendNotification
When an event is triggered that your Notification Provider is registered as a handler for, the NotificationService
in the Medusa backend executes this method of your Notification Provider.
In this method, you can perform the necessary operation to send the Notification. For example, you can send an email to the customer when they place an order.
Example
class EmailSenderService extends AbstractNotificationService {
// ...
async sendNotification(
event: string,
data: any,
attachmentGenerator: unknown
): Promise<{
to: string;
status: string;
data: Record<string, unknown>;
}> {
if (event === "order.placed") {
// retrieve order
const order = await this.orderService.retrieve(data.id)
// TODO send email
console.log("Notification sent")
return {
to: order.email,
status: "done",
data: {
// any data necessary to send the email
// for example:
subject: "You placed a new order!",
items: order.items,
},
}
}
}
// ...
}
Parameters
event
stringRequiredorder.placed
.data
unknownRequiredorder.placed
event is triggered,
the eventData
object contains the property id
which is the ID of the order that was placed. You can refer to the
Events reference for information on all events and their payloads.attachmentGenerator
unknownRequiredNotificationService
using the
registerAttachmentGenerator
method,
you have access to it here. You can use the attachmentGenerator
to generate on-demand invoices or other documents. The default value of this parameter is null
.Returns
The sending details.
resendNotification
This method is used to resend notifications, which is typically triggered by the Resend Notification API Route.
Example
class EmailSenderService extends AbstractNotificationService {
// ...
async resendNotification(
notification: any,
config: any,
attachmentGenerator: unknown
): Promise<{
to: string;
status: string;
data: Record<string, unknown>;
}> {
// check if the receiver should be changed
const to: string = config.to || notification.to
// TODO resend the notification using the same data
// that is saved under notification.data
console.log("Notification resent")
return {
to,
status: "done",
data: notification.data, // make changes to the data
}
}
}
Parameters
notification
unknownRequiredsendNotification
. It includes the to
and data
attributes which are populated originally using the to
and data
properties of
the object you return in sendNotification.config
unknownRequiredto
field. If specified, it will be available in this config object.attachmentGenerator
unknownRequiredNotificationService
using the
registerAttachmentGenerator
method,
you have access to it here. You can use the attachmentGenerator
to generate on-demand invoices or other documents. The default value of this parameter is null
.Returns
The resend details.
Subscribe with Loaders
After creating your Notification Provider Service, you must create a Loader that registers this Service as a notification handler of events.
For example, to register the email-sender
Notification Provider as a handler for the order.placed
event, create the file src/loaders/notification.ts
with the following content:
This loader accesses the notificationService
through the MedusaContainer. The notificationService
has a subscribe
method that accepts 2 parameters. The first one is the name of the event to subscribe to, and the second is the identifier of the Notification Provider that's subscribing to that event.
Test Sending a Notification
Make sure you have an event bus module configured in your Medusa backend. You can learn more on how to do that in the Configurations guide.
Then:
1. Run the build
command in the root directory of your Medusa backend:
2. Start your Medusa backend:
3. Place an order either using the REST APIs or using the storefront.
4. After placing an order, you can see in your console the message “Notification Sent”. If you added your own notification sending logic, you should receive an email or alternatively the type of notification you’ve set up.
Test Resending a Notification
To test resending a notification:
-
Retrieve the ID of the notification you just sent using the List Notifications API Route. You can pass as a body parameter the
to
orevent_name
parameters to filter out the notification you just sent. -
Send a request to the Resend Notification API Route using the ID retrieved from the previous request. You can pass the
to
parameter in the body to change the receiver of the notification. -
You should see the message “Notification Resent” in your console.