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
{
  "name": "order_notifications",
  "label": "Order Notifications",
  "description": "Notification group for order-related messages",
  "templates": {
    "sms": [
      "order_confirmation_sms",
      "order_shipped_sms"
    ],
    "email": [
      "order_confirmation_email",
      "order_shipped_email"
    ],
    "whatsapp": [
      "order_confirmation_whatsapp",
      "order_shipped_whatsapp"
    ]
  }
}
{
  "name": "order_notifications",
  "label": "Order Notifications",
  "description": "Notification group for order-related messages",
  "templates": {
    "sms": [
      "order_confirmation_sms",
      "order_shipped_sms"
    ],
    "email": [
      "order_confirmation_email",
      "order_shipped_email"
    ],
    "whatsapp": [
      "order_confirmation_whatsapp",
      "order_shipped_whatsapp"
    ]
  }
}
﻿
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
{
  "data": {
    "name": "order_notifications"
  }
}
{
  "data": {
    "name": "order_notifications"
  }
}
﻿
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
{
  "notifications": [
    {
      "data": {
        "otp": "235523"
      },
      "sms": {
        "senderId": "DLHVRY",
        "provider": "aws-pinpoint",
        "to": [
          {
            "countryCode": "91",
            "number": "9812345600"
          }
        ]
      },
      "email": {
        "provider": "aws-ses-default",
        "from": "[email protected]",
        "replyTo": "[email protected]",
        "to": [
          "[email protected]"
        ],
        "cc": [
          "[email protected]"
        ],
        "bcc": [
          "[email protected]"
        ],
        "attachments": [
          "https://example.com/attachments/invoice.pdf"
        ]
      },
      "whatsapp": {
        "from": "123324242",
        "provider": "infobip",
        "media": {
          "document": {
            "url": "https://example.com/documents/user_guide.pdf",
            "fileName": "user_guide.pdf"
          },
          "image": {
            "url": "https://example.com/images/product_image.jpg"
          },
          "location": {
            "latitude": 37.7749,
            "longitude": -122.4194
          }
        },
        "buttons": [
          "Track Order",
          "Contact Support"
        ],
        "to": [
          {
            "countryCode": "91",
            "number": "9812345600"
          }
        ]
      }
    }
  ],
  "callback": {
    "url": "https://os1-test-msg-callback.requestcatcher.com/test",
    "meta": {
      "clientId": "client123",
      "notificationId": "notification456"
    }
  }
}
{
  "notifications": [
    {
      "data": {
        "otp": "235523"
      },
      "sms": {
        "senderId": "DLHVRY",
        "provider": "aws-pinpoint",
        "to": [
          {
            "countryCode": "91",
            "number": "9812345600"
          }
        ]
      },
      "email": {
        "provider": "aws-ses-default",
        "from": "noreply@example.com",
        "replyTo": "support@example.com",
        "to": [
          "user@example.com"
        ],
        "cc": [
          "manager@example.com"
        ],
        "bcc": [
          "archive@example.com"
        ],
        "attachments": [
          "https://example.com/attachments/invoice.pdf"
        ]
      },
      "whatsapp": {
        "from": "123324242",
        "provider": "infobip",
        "media": {
          "document": {
            "url": "https://example.com/documents/user_guide.pdf",
            "fileName": "user_guide.pdf"
          },
          "image": {
            "url": "https://example.com/images/product_image.jpg"
          },
          "location": {
            "latitude": 37.7749,
            "longitude": -122.4194
          }
        },
        "buttons": [
          "Track Order",
          "Contact Support"
        ],
        "to": [
          {
            "countryCode": "91",
            "number": "9812345600"
          }
        ]
      }
    }
  ],
  "callback": {
    "url": "https://os1-test-msg-callback.requestcatcher.com/test",
    "meta": {
      "clientId": "client123",
      "notificationId": "notification456"
    }
  }
}
﻿
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
{
  "label": "Updated Shipment Notifications",
  "description": "Updated notification group for sending shipment updates",
  "templates": {
    "whatsapp": [
      "Your shipment *{{shipmentId}}* has been dispatched from our warehouse. Expected delivery date: *{{deliveryDate}}*. You can track your shipment using this URL: {{trackingUrl}}",
      "Good news! Your shipment *{{shipmentId}}* is out for delivery and will reach you today by *{{deliveryTime}}*. If you have any special instructions for the delivery, please reply to this message or contact our support team at *{{supportContact}}*. Thank you for choosing our services!"
    ]
  }
}
{
  "label": "Updated Shipment Notifications",
  "description": "Updated notification group for sending shipment updates",
  "templates": {
    "whatsapp": [
      "Your shipment *{{shipmentId}}* has been dispatched from our warehouse. Expected delivery date: *{{deliveryDate}}*. You can track your shipment using this URL: {{trackingUrl}}",
      "Good news! Your shipment *{{shipmentId}}* is out for delivery and will reach you today by *{{deliveryTime}}*. If you have any special instructions for the delivery, please reply to this message or contact our support team at *{{supportContact}}*. Thank you for choosing our services!"
    ]
  }
}
﻿
Retrieve notifications
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.
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
{
  "modes": {
    "sms": true,
    "email": false,
    "whatsapp": true
  }
}
{
  "modes": {
    "sms": true,
    "email": false,
    "whatsapp": true
  }
}
﻿
﻿

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.

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	-

Parameter	Description
notification	The name of the notification.

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

Updated 19 Apr 2024

Did this page help you?

Messaging

Mobile Push Notifications