Usage Guide

Learn how to integrate and use OsmoX for sending notifications

Usage Guide

Welcome to the usage guide for OsmoX, a powerful notification management system designed to simplify the process of sending notifications through various channels.

Overview

OsmoX offers a streamlined solution for sending notifications via different channel providers:

• The system monitors the notify_notifications database table and automatically dispatches notifications for records with a PENDING status
• For records with AWAITING_CONFIRMATION status, the system verifies successful message delivery (when supported by the provider)
• Users can set up custom webhooks for verification purposes

Quick Start

1. Set up the codebase

   Follow either the Development Setup or Production Setup guide

2. Get Bearer Token

   OsmoX has seeded an Admin user. Use the login API to get your authentication token

3. Create an Application

   Create a new Application using the create application API

4. Create a Provider

   Create a Provider that will be used to send notifications using the create provider API

5. Generate API Key

   Generate a new x-api-key for your application using the generate API key endpoint

6. Send Notifications

   Use the x-api-key header to send notifications via the OsmoX API

Using the API

Authentication Header

To authenticate API requests, add the API key to the x-api-key header:

x-api-key: YOUR_SERVER_API_KEY

Create Notification

Endpoint: POST /notifications

Sample Request:

{
  "providerId": 1,
  "data": {
    "from": "[e-mail]",
    "to": "[e-mail]",
    "subject": "Test subject",
    "text": "This is a test notification",
    "html": "<b>This is a test notification</b>"
  }
}

Sample Response:

{
  "status": "success",
  "data": {
    "notification": {
      "providerId": 1,
      "data": {
        "from": "[e-mail]",
        "to": "[e-mail]",
        "subject": "Test subject",
        "text": "This is a test notification",
        "html": "<b>This is a test notification</b>"
      },
      "applicationId": 1,
      "createdBy": "OsmoX",
      "updatedBy": "OsmoX",
      "channelType": 1,
      "result": null,
      "notificationSentOn": null,
      "id": 36,
      "deliveryStatus": 1,
      "createdOn": "2023-09-08T13:11:52.000Z",
      "updatedOn": "2023-09-08T13:11:52.000Z",
      "status": 1,
      "retryCount": 0
    }
  }
}

Tracking Notification Status

OsmoX updates the delivery_status and result columns to provide information on the notification’s status. Use these columns to track the progress of your notifications.

Available Channel Types

OsmoX supports multiple channel types for notifications:

Channel Type	Value	Documentation
SMTP	1	SMTP Guide
Mailgun	2	Mailgun Guide
WhatsApp - 360Dialog	3	360Dialog Guide
WhatsApp - Twilio	4	Twilio WhatsApp Guide
SMS - Twilio	5	Twilio SMS Guide
SMS - Plivo	6	Plivo Guide
WhatsApp - Twilio Business	7	Twilio Business Guide
Push Notification - SNS	9	AWS SNS Push Guide
Voice Call - Twilio	10	Twilio Voice Guide
Email - AWS SES	11	AWS SES Guide
SMS - AWS SNS	12	AWS SNS SMS Guide

Channel type 8 (SMS - KAPSystem) is no longer supported.

Delivery Status Information

OsmoX provides different delivery status options to reflect the state of your notifications:

Status	Value	Description
PENDING	1	The notification is awaiting processing
IN PROGRESS	2	The notification is currently being sent
AWAITING_CONFIRMATION	3	The notification is awaiting confirmation
QUEUED_CONFIRMATION	4	The notification is added to confirmation queue
SUCCESS	5	The notification was successfully delivered
FAILED	6	The notification delivery failed

For more information, see the Delivery Status Lifecycle guide.

Test Mode Feature

OsmoX Admin users can enable/disable Test Mode for applications. This feature allows functional testing without sending notifications to real recipients.

Test Mode Guide

Learn how to configure and use test mode for safe testing

Key Points

• Providers associated with test mode enabled applications DO NOT send notifications to end recipients
• Admin users can add a whitelist to send notifications only to specific recipients
• Whitelist must be either null or a valid JSON with provider IDs as keys and arrays of recipient strings as values

Example Whitelist:

{
  "2": ["[e-mail]", "[e-mail]"],
  "5": ["[phone]", "[phone]"]
}

Direct Database Access

Developers can also populate the notify_notifications database table directly, though using the API is recommended. For database structure details, see the Database Design documentation.