Inform API

Overview

Inform facilitates a unified messaging infrastructure across multiple channels with a single API for building and managing transactional alerts.

Transactional Alerts can be sent in the following scenarios:

  • Order/Booking/Purchase confirmations
  • Shipping/Delivery confirmations and updates
  • Security and account alerts
  • Password resets
  • OTP (one-time password)
  • User invitations and shares
  • User inaction related to previous transactions
  • Fraud prevention/security alerts

The Inform API sends notifications to all the channels simultaneously for a specified Live Alert. You can use the Inform API to do the following:

  1. Send a transactional message on a single channel like SMS or Email or Push
  2. Send transactional messages on multiple channels

Glossary

We’ve put together a list of terminology that you will encounter when using the Inform Service API.

Alert ID

This is the unique identifier for an Alert. This field will be used to identify the Alert configured in the MoEngage Dashboard that contains the template for the notifications to be sent to the user.

Test Alert ID

When creating an Alert, you can test it on an external console and MoEngage provides a unique identifier called Test Alert ID for this purpose.

Live and Test Alerts

Live Alerts Test Alerts

The unique Identifier for a published Alert is called the Alert ID.

The unique identifier for a test Alert is called the Test Alert ID.

The Alert Logs are available in the Alert Info Section.

The Test Alert Logs are available in the third step of Alert creation.

API Endpoint

For Live Alerts

Live Alert Endpoint
POST https://inform-api-0X.moengage.com/v1/send

For Test Alerts

Test Alert Endpoint
POST https://sandbox-inform-api-0X.moengage.com/v1/send

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

  1. Navigate to Settings -> Account -> APIs.
  2. Click the Copy icon in the Inform tile in the API Keys section to copy the API Key.
  3. Use the App ID as the username and the Inform API Key as the password to generate the authentication header.

Old UI

  1. Navigate to Settings -> APIs -> INFORM Settings.
  2. Click here to show APP Secret to view the API SECRET.
  3. Use the APP ID as the username and the API SECRET as the password to generate the authentication header.

Regenerate API SECRET

The API SECRET can be regenerated on the MoEngage Dashboard in the INFORM API Settings section discussed above.

Please DO NOT regenerate the key unless there is a security breach. Once you generate a different API SECRET KEY and save it, API calls using the older SECRET KEY won't work.

Request Headers

Key Sample Values Description

MOE-APPKEY

{"MOE-APPKEY": "APP ID"}

This is the APP ID of your MoEngage account and needs to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. For more information, refer to Authentication.

Authorization

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

Content-Type

application/JSON

Set the Content-Type header to application/JSON for using the Inform API.

Request Body

Key Type Value Description

alert_id

Mandatory

String

This field uniquely identifies the Alert to be sent to the user. For the staging endpoint, use the test alert id and for the live endpoint, use the alert id. For more information, refer to Live and Test Alerts

user_id

Optional

String

This is the unique user identifier information you maintain. This information should be passed in the request to facilitate the mapping of the channel events back to the user profile to which this user_id is associated in MoEngage. MoEngage stores this unique identifier as the Client ID in the user profile.

transaction_id

Mandatory

String

This is the unique identifier denoting the transaction for which the Alert is being sent to the user. This information is maintained by the brand and is passed in the request. The maximum length allowed for this field is 50 characters. The Inform API supports idempotency using this parameter. If a  request contains a transaction_id and is successful and another request with the same transaction id is received within 5 minutes of the successful request, the new request would be deemed a duplicate one.

payloads

Mandatory

JSON Object

[payloadobject, payloadobject..]

Payload object - 

<medium>: {

“recipient”:<recipient value>,

“peronsalized_attributes”:<json object of personalized key-value parameters>

}

]

The payload contains the following channel-level information for all the configured channels:

  • recipient

    This field contains the following information:

    SMS Channel: <mobile number> 

    Email Chanel: <email id>

    Push Channel: <push token>

    For information on how recipient and user_id fields are used, refer to Identifying the user for sending Alerts.  

  • personalized attributes

    This field contains the personalized attributes for each channel configured for the Alert. This information would be passed by the brand when invoking the Inform API Service.

  • personalized attachments

    This field contains the personalized attachments for the email channel. If email attachments are specified as to be Uploaded via API during Alert creation, this field should be added to the payload and the attachment should be passed using the attachment key specified during Alert creation. For example, if the attachment key is specified as sample_attachment_key during Alert creation for an attachment, it should be passed in the request as follows:

    "personalized_attachments": {
       "sample_attachment_key":      "YOUR_sample_attachment_key_VAL_HERE"
    }

Note:

    1.  At least one channel is mandatory in the API request and only a maximum of two channels can be configured for an Alert.
    2. If multiple channels are configured in the Alert, and the payload contains information for only some channels, MoEngage will send the Alerts to the channels for which information is present and ignore the channels for which information is not available in the payload.
    3. The total size of the attachments should be less than 4 MB. You can attach up to 5 files.

Sample Requests for a Live Alert Without Personalization

Case 1: One channel is configured for the Alert

Only SMS Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alert_id": "636b77e6e2cf83277195fb60",
  "user_id": "USER_ID",
  "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
  "payloads": {
     "SMS": {
        "recipient": "123456789"
     }
  }
}'     

 

Only Email Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b77e6e2cf83277195fb60",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "EMAIL": {
            "recipient": "john.doe@moengage.com"
        }
    }
}'

Only Push Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alert_id": "636b77e6e2cf83277195fb60",
  "user_id": "USER_ID",
  "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
  "payloads": {
      "PUSH": {
            "recipient": "<push-token>"
        }
  }
}' 

Case 2: Multiple channels are configured for the Alert

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b77e6e2cf83277195fb60",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "PUSH": {
            "recipient": "<push-token>"
        },
        "EMAIL": {
            "recipient": "john.doe@moengage.com"
        }
    }
}'

Sample Request for a Live Alert with Personalization

Case 1: One channel is configured for the Alert

Only SMS Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b77e6e2cf83277195fb60",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "SMS": {
            "recipient": "123456789",
            "personalized_attributes": {
                "firstname": "YOUR_firstname_ATTRIBUTE_VAL_HERE",
                "orderid": "YOUR_orderid_ATTRIBUTE_VAL_HERE",
                "deliverydate": "YOUR_deliverydate_ATTRIBUTE_VAL_HERE",
                "deliveryslot_starttime": "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE",
                "deliveryslot_endtime": "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
            }
        }
    }
}'

Only Email Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b9d5de2cf8328549503b9",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "EMAIL": {
            "recipient": "john.doe@moengage.com",
            "personalized_attributes": {
                "firstname": "YOUR_firstname_ATTRIBUTE_VAL_HERE",
                "orderid": "YOUR_orderid_ATTRIBUTE_VAL_HERE",
                "deliverydate": "YOUR_deliverydate_ATTRIBUTE_VAL_HERE",
                "deliveryslot_starttime": "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE",
                "deliveryslot_endtime": "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
            },
            "personalized_attachments": {
                "order_summary": "YOUR_order_summary_VAL_HERE"
            }
        }
    }
}'

Only Push Channel

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b77e6e2cf83277195fb60",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "PUSH": {
            "recipient": "<push-token>",
            "personalized_attributes": {
                "firstname": "YOUR_firstname_ATTRIBUTE_VAL_HERE",
                "orderid": "YOUR_orderid_ATTRIBUTE_VAL_HERE",
                "deliverydate": "YOUR_deliverydate_ATTRIBUTE_VAL_HERE",
                "deliveryslot_starttime": "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE",
                "deliveryslot_endtime": "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
            }
        }
    }
}'

 

Case 2: Multiple channels are configured for the Alert

cURL Node.js Go PHP Python Ruby Java
curl --location --request POST 'https://inform-api-0X.moengage.com/v1/send' \
--header 'MOE-APPKEY: YOUR_APP_KEY_HERE' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alert_id": "636b77e6e2cf83277195fb60",
    "user_id": "USER_ID",
    "transaction_id": "YOUR_TRANSACTION_ID_VAL_HERE",
    "payloads": {
        "PUSH": {
            "recipient": "<push-token>",
            "personalized_attributes": {
                "firstname": "YOUR_firstname_ATTRIBUTE_VAL_HERE",
                "orderid": "YOUR_orderid_ATTRIBUTE_VAL_HERE",
                "deliverydate": "YOUR_deliverydate_ATTRIBUTE_VAL_HERE",
                "deliveryslot_starttime": "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE",
                "deliveryslot_endtime": "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
            }
        },
        "EMAIL": {
            "recipient": "john.doe@moengage.com",
            "personalized_attributes": {
                "firstname": "YOUR_firstname_ATTRIBUTE_VAL_HERE",
                "orderid": "YOUR_orderid_ATTRIBUTE_VAL_HERE",
                "deliverydate": "YOUR_deliverydate_ATTRIBUTE_VAL_HERE",
                "deliveryslot_starttime": "YOUR_deliveryslot_starttime_ATTRIBUTE_VAL_HERE",
                "deliveryslot_endtime": "YOUR_deliveryslot_endtime_ATTRIBUTE_VAL_HERE"
            }
        }
    }
}'

Response Parameters

Key Description

message

This field contains a brief description of the request status. 

request_id

This field contains the unique identifier for the request and is present in the response body only for the following cases:

  1. Successful request
  2. Duplicate request

err_code

This field is present in the response body only when the request is unsuccessful and contains the error code.

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is submitted to MoEngage.

Note: For errors in the channel-level payload, the error information is present in the logs on the dashboard. 

400

Bad Request

This response is returned in the following cases: 

  1. When the payload is empty or invalid
  2. Invalid Alert ID (alert) being sent
  3. Incorrect Channel in the Payload (When the Payload contains information about channels that are not configured in the Alert).
  4. When the transaction_id exceeds the allowed limit 
  5. When the Alert ID of a paused or stopped or archived Alert is used in the request.

401

Authorization Failed

This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.

409

Duplicate Request

This response is returned when a request is sent with the same transaction_id value as a previously successful or in-progress request. For more information, refer to Duplicate requests.

429

Rate Limit Reached

This response is returned when the number of requests per minute has exceeded the rate limit.

500

Internal Server error

This response is returned when the system runs into an unexpected error. You can try for a maximum of 3 times with exponential backoff.

Sample Response

200 400 401 409 429 500
Success Response
{ "message": "Alert request Submitted", "request_id": "df757a58-971a-464c-803f-e8ecf9110943" }

Postman Collection

We have made it easy for you to test the APIs.Click here to view it in Postman. 

FAQs

  • What is the Rate Limit?
    The default rate limit is 10K RPM.
  • How are Duplicate Requests handled?
    A request is deemed duplicate in the case following cases:
    1. It is received within 5 minutes of a previously successful request containing the same transaction_id
    2. It is received within 5 minutes of a previous request which is ‘In Progress’ (being processed) and contains the same transaction_id

Duplicate requests are dropped and not reprocessed.

  • What happens when a vendor does not accept requests from MoEngage?
    When the vendor does not accept requests from MoEngage, MoEngage retries every request a maximum of five times with 200ms exponential backoff.
  • Are Alert Logs stored in MoEngage?
    Alert logs are stored for up to 30 days for every Alert in MoEngage.

Previous

Next

Was this article helpful?
2 out of 4 found this helpful

How can we improve this article?