Register Message Notifications
The messaging notifications feature simplifies the process for the app developers to register their app’s messages/notifications so that the tenant admins can review and enable/disable messages as per the tenant’s business needs. The feature also enables app developers to register their notifications along with the channels and templates to use to send the notifications. The developers can use the registered notifications to quickly send messages in multiple channels using a single API call.
- Notification Registration: Developers can register notifications using the Messaging Notifications APIs, specifying details such as the notification name, description, and associated templates with channels to use (SMS, email, and WhatsApp).
- Tenant Admin Control: Tenant admins get the ability to review the registered notifications and decide whether to enable or disable them.
- Default Template Registration: Additionally, developers can register templates while registering notifications and then use those templates when sending SMS, email, and WhatsApp notifications.
- Multi-Channel Support: The feature enables developers to send messages using multiple channels/modes using a single API call. Instead of making separate API calls for each channel, developers can leverage the SendNotifications API to send SMS, Email, and WhatsApp notifications with a single request.
This guide covers the available APIs for registering and updating notifications.
To register notifications supported by your application, use the CreateMessageNotifications API. This API allows you to specify the notification details, such as app ID, notification name, templates to use with supported channels.
Body parameters
Field Name | Description |
---|---|
name* | Name of the notification group. |
label* | A human-readable name or text that describes the notification group. |
description | Additional details to describe the notification group. |
templates* | Allowed templates for respective modes for this notification group. |
templates.sms | Array of SMS templates. |
templates.email | Array of email templates. |
templates.whatsapp | Array of WhatsApp templates.
|
The following CreateMessageNotifications request registers a new notification group with templates for the SMS, email, and WhatsApp channels.
In this example, a notification group named "order_notifications" is created with template names for SMS, email, and WhatsApp channels. The template names refer to pre-defined templates that should be registered separately.
The response includes the data object with the name of the notification.
Use the SendMessageNotifications API to send messages to users via multiple channels such as SMS, email, and WhatsApp with a single API call. This request allows developers to specify notification details, recipient information, and provider configurations.
Body Parameters
Here's a markdown table for the SendMessageNotifications request using the provided schema:
Parameter | Description |
---|---|
notifications* | One Notification can be sent to multiple users via multiple modes. |
data* | Example: OrderedMap { "otp": "235523" } |
sms | SMS Notification |
senderId | A Sender ID is a unique name or standard mobile number that shows in the "from" field of your text messages on your phone. If not provided, senderId of template will be used. Example: DLHVRY |
provider | Name of config instance used for sending message. Optional parameter. If not provided, os1 default provider will be used. Example: aws-pinpoint |
to* | Minimum items: 1 |
countryCode* | Pattern: ^\\+(\\d{1}\\-)?(\\d{1,3})$ Example: 91 |
number* | Pattern: ^{\\d}$ Minimum length: 4, Maximum length: 10 Example: 9812345600 |
Email Notification | |
provider | Name of config instance used for sending message. Optional parameter. If not provided, os1 default provider will be used. Example: aws-ses-default |
from | Email address of sender. If not provided, sender provided in template will be used. Pattern: ^[a-zA-Z0-9._+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,6}$ |
replyTo | Email address to which reply email will be sent. Pattern: ^[a-zA-Z0-9._+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,6}$ Minimum length: 1 |
to* | Recipients' email addresses. Pattern: ^[a-zA-Z0-9._+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,6}$ Nullable: false, Minimum length: 1 |
cc | Recipients to be in CC of the email. Pattern: ^[a-zA-Z0-9._+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,6}$ Nullable: false, Minimum length: 1 |
bcc | Recipients to be in BCC of the email. Pattern: ^[a-zA-Z0-9._+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,6}$ Nullable: false, Minimum length: 1 |
attachments | Attachment links. Total maximum combined size of attachments is allowed only up to 10MB. Maximum: 5 Example: https://console.getos1.com/header/static/media/logo.0802580f6e1b1127d6e519f4a3cbea50.svg |
WhatsApp Notification | |
from | Sender's standard mobile number from which messages would be sent. If not provided, "from" of template will be used. Example: 123324242 |
provider | Name of config instance used for sending message. Optional parameter. If not provided, os1 default provider will be used. Example: infobip |
media | Media options supported in WhatsApp message like documents or images. |
document | - |
url* | Link of the document to be sent along with message. Maximum document size is 100MB. |
fileName | Name of the document attached. |
image | - |
url* | Link of the image to be sent along with message. Supported image types are JPG, JPEG, PNG. Maximum image size is 5MB. |
location | - |
latitude* | Latitude of a location. Minimum: -90, Maximum: 90 |
longitude* | Longitude of a location. Minimum: -90, Maximum: 90 |
buttons | Buttons to be attached with the messages. |
string | Values of the placeholders in dynamic URLs provided. Optional if URL is static or if URL is not added in the template type. |
to* | Minimum items: 1 |
countryCode* | Pattern: ^\\+(\\d{1}\\-)?(\\d{1,3})$ Example: 91 |
number* | Pattern: ^{\\d}$ Minimum length: 4, Maximum length: 10 Example: 9812345600 |
callback | Details of callback for sending message delivery details. |
url* | Example: https://os1-test-msg-callback.requestcatcher.com/test |
meta | - |
Example request
The example sends a notification with the following details:
- The data object contains an OTP value to be used in the notification templates.
- The sms object specifies the SMS notification details, including the sender ID, provider, and recipient information.
- The email object specifies the email notification details, including the provider, sender email, reply-to email, recipient emails (to, cc, bcc), and an attachment URL.
- The whatsapp object specifies the WhatsApp notification details, including the sender number, provider, media attachments (document, image, location), buttons, and recipient information.
- The callback object specifies the callback URL and metadata for the notification status updates.
Call UpdateMessageNotificationTemplates to update templates associated with a notification.
Parameter | Description |
---|---|
notification | The name of the notification. |
The following UpdateMessageNotificationTemplates request updates What’sApp template while keeping the same label and description fields. The templates object only includes the WhatsApp array, leaving the sms and email arrays unchanged.
You can retrieve a single notification by name or all notifications using the following endpoints.
- Use the GetMessageNotificationDetails endpoint to retrieve a notification by providing the notification name in the path.
- Use the GetAllMessageNotifications endpoint to retrieve a list of notifications providing the appId and mode query parameters.
The UpdateNotificationModes endpoint allows business admins to choose to enable or disable notification modes an app can send in the UI.
Parameter | Description |
---|---|
notification | The name of the notification. |
Parameter | Description |
---|---|
Modes | The allowed modes for this notification group. Note: All notification modes are disabled by default. |
modes.sms | The SMS mode |
mode.email | The email mode |
mode.whataspp | The whatsapp mode |
The following UpdateNotificationMode request sets sms and whatsapp to true and leaves email false.