OS1 Services
...
Messaging and Mobile Push Noti...
Messaging

Register Message Notifications

14min

Overview

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.

Benefits

  • 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.


Managing Notifications

This guide covers the available APIs for registering and updating notifications.

Register 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.



JSON


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.

JSON


Send messages with notificationId

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

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

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

JSON


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.

Update notification templates

Call UpdateMessageNotificationTemplates to update templates associated with a notification.

Path parameters

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.

Text


Retrieve notifications

You can retrieve a single notification by name or all notifications using the following endpoints.

Update notification modes

The UpdateNotificationModes endpoint allows business admins to choose to enable or disable notification modes an app can send in the UI.

Path parameters

Parameter

Description

notification

The name of the notification. 

Body parameters

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.

Text