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:

      1. Order/Booking/Purchase confirmations
      2. Shipping/Delivery confirmations and updates
      3. Security and account alerts
      4. Password resets
      5. OTP (one-time password)
      6. User invitations and shares
      7. User inaction related to previous transactions
      8. 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
      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

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

For Test Alerts

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

MoEngage hosts each customer in a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping here. Replace the value of 'X' in the endpoint URL based on your DataCenter.

Authentication

All Inform requests will be authenticated through Basic Authentication. Do the following to generate the Basic Authentication header:

    1. Navigate to Settings > APIs > INFORM Settings
    2. Copy the APP ID and API SECRET
    3. Generate the Authentication string using base64 concatenation of APP ID and API SECRET

Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. Do the following to generate the Auth header:

    1. Add a colon after the user name (APP key) and concatenate it with the password (API SECRET). 
    2. Encode the concatenated string using base64 encoding.
    3. Pass the encoded string in the HTTP authorization header as follows: {"Authorization":" Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

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. Navigation: Settings -> API -> General Settings -> Inform section. For more information, refer to Authentication.

Authorization

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

This is the authentication parameter for access control and needs to be passed along with the request. The APPKEY and API SECRET need to be picked up from the Inform API Settings in MoEngage Dashboard and a Basic Authorization header needs to be created and set in the header. For more information, 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 maintained by you. 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 mobile number for the SMS channel and the email id for the Email channel.

  • personalized attributes

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

Note:

    1.  At least one channel is mandatory in the API request.
    2. If multiple channels are configured in the Alert and the payload contains information for only some of the 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.

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"
        }
    }
}'
        

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": {
        "SMS": {
            "recipient": "123456789"
        },
        "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"
            }
        }
    }
}'

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": {
        "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"
            }
        },
        "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 was not successful 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" }

FAQs

1. What is the Rate Limit?

The default rate limit is 10K RPM.

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

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

4. Are Alert Logs stored in MoEngage?

Alert logs are stored for up to 30 days for every Alert in MoEngage.

Was this article helpful?
0 out of 0 found this helpful