usage-guide.md

Usage Guide for OsmoX

Introduction

Welcome to the usage guide for OsmoX, a powerful notification management system designed to simplify the process of sending notifications through various channels. This guide will walk you through the steps of integrating OsmoX into your application and making the most of its features.

Table of Contents

• Usage Guide for OsmoX
  • Introduction
  • Table of Contents
  • 1. Overview
  • 2. Pushing Data to the Database
  • 3. Using the OsmoX API
    • x-api-key Header
  • 4. Tracking Notification Status
  • 5. Available Channel Types
  • 6. Delivery Status Information

1. Overview

OsmoX offers a streamlined solution for sending notifications via different channels. It operates by monitoring the notify_notifications database table and automatically dispatches notifications for records with a PENDING status.

2. Pushing Data to the Database

Developers have the flexibility to populate the notify_notifications database table directly or opt for the recommended approach of utilizing the OsmoX API. By following this method, the notification processing is seamlessly managed by OsmoX.

3. Using the OsmoX API

To use the OsmoX API, follow these steps:

• Method: POST
• Endpoint: /notifications

x-api-key Header

To add the API key to the x-api-key header, use the following format:

x-api-key: SERVER_API_KEY_VALUE

Replace SERVER_API_KEY_VALUE with the actual API key value you want to include in the header.

Sample Request Body:

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

Response:

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

4. 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 in database.

5. Available Channel Types

OsmoX supports multiple channel types, allowing you to choose the most suitable one for your notifications. Currently, the available channel types are:

Channel Type	Value	Document
SMTP - Simple Mail Transfer Protocol	1	SMTP
Mailgun	2	Mailgun
WhatsApp - 360Dialog	3	WhatsApp - 360Dialog
WhatsApp - Twilio	4	WhatsApp - Twilio
SMS - Twilio	5	SMS - Twilio
SMS - Plivo	6	SMS - Plivo
WhatsApp - Twilio (Business)	7	WhatsApp - Twilio (Business)
SMS - KAPSystem	8	SMS - KAPSystem
PushNotification - SNS	9	Push Notification - SNS
Voice Call - Twilio	10	Voice Call - Twilio
Email - AWS SES	11	Email - AWS SES
SMS - AWS SMS SNS	12	SMS - AWS SMS SNS

6. Delivery Status Information

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

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