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.

Alert Reference Name

This field is used to identify the Alert using your reference Name and can be used to identify the alert as an alternative to Alert ID.

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.

Test Alert Reference Name

Test Alert Reference Name is configured while adding the alert on the Dashboard to send this Test Alert request to an external console.

Live and Test Alerts (Add a row for Reference name)

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
https://api-0X.moengage.com/v1.0/alerts/send

For Test Alerts

Test Alert Endpoint
https://sandbox-api-0X.moengage.com/v1.0/alerts/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 Workspace ID (or 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

alert_reference_name

Mandatory

String

This field is used to identify the Alert using your reference Name and can be used to identify the alert as an alternative to Alert ID.

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 and should be sent as a base64-encoded string. 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 and a maximum payload size of 100KB is allowed for personalised attributes.
    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",
  "alert_reference_name": "Demo_ID",
  "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",
"alert_reference_name": "Demo_ID", "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",
  "alert_reference_name": "Demo_ID",
  "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",
    "alert_reference_name": "Demo_ID",
    "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",
    "alert_reference_name": "Demo_ID",
    "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",
    "alert_reference_name": "Demo_ID",
    "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",
    "alert_reference_name": "Demo_ID",
    "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",
    "alert_reference_name": "Demo_ID",
    "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 and the channel-level details are present in the API Response Details.

Note: For errors in the channel-level payload, the error information is present in the logs on the dashboard. To learn more, see API Response Details.

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.

How Does Inform API Work & Respond?

info

Info

Reach out to your Customer Success Manager to enable sending the channel level details as part of your API response.

Inform API works in two steps as described below:

  1. A check is performed to verify if the API request received for Inform is valid.
  2. If valid, the second process is to resolve the content and send a message using the partner.

The response codes are shared in wxyzab format as described below:
w - Status (failures are indicated with 1 and success is indicated with 2)
x - Category of the error
y - Request is considered for parallel request (parallel requests is indicated with 0 and fallback requests are indicated with 1)
z - Can this request be retried by you(0 indicates it cannot be retried with same details)
ab - Reason details for the error

 

Below are the Category details:

Category Code Details
1 Unauthorized
2 Bad Request
4 Internal Server Error / Ratelimit

 

The Reason details are given below with each Reason Code holding specific meanings:

Reason Code Details
1 Invalid Credentials
2 Invalid Alert ID
3 Missing Transaction ID
4 Duplicate Transaction ID
5 Long Transaction ID
6 Invalid Payload
7 Personalisation Attribute
9 Internal Server Error
10 Rate Limit
11 Personalisation Failed
12 Invalid Recipient details
13 Vendor configuration errors
14 Vendor not available
15 Vendor Payload Rejection
16 Unexpected Error Occurred
17 Invalid Origin Source

 

Payload Errors Before Accepting the API Request

The list of the payload errors that can occur before accepting the API request and the equivalent response codes to be shared under HTTP status code 4xx for different scenarios across each functionality is given below:

Payload Errors Description Scenarios Response Codes Resolution

Authorization Failure

This error occurs when invalid authorization details such as App Key (Workspace ID) or Password are shared.

  • No Auth values passed.
  • Incorrect Auth Values Passed
  • Incorrect Password shared.
  • No Auth & No Key Passed
  • No App key shared / Empty App Key
  • Incorrect App Key shared
{ "message": "Authorization Failed", "err_code": "UNAUTHORIZED" } Recheck the authorization details listed in Settings / Check if you passed the Test Alert ID on Live Endpoint.

Invalid Alert ID

This error occurs when an invalid Alert ID or external reference name is shared.

  • Missing Alert ID
  • Alert ID <24 characters
  • Alert ID > 24 Characters
  • Invalid Alert ID
  • Inactive Alert ID
{"message": "Invalid Alert ID“, "err_code": "BAD_REQUEST", “status_code”:120002} Recheck the Alert ID or external reference name listed on the Info page.

Invalid Transaction ID

This error occurs when the Transaction ID is not shared.

Missing Transaction ID {"message": "Invalid Transaction ID“, "err_code": "BAD_REQUEST", “status_code”:120003}

Share the transaction ID using the key name transaction_id as part of the API Call.

 

Long Transaction ID

This error occurs when the Transaction ID is invalid.

Long Transaction ID {"message": "Long Transaction ID“, "err_code": "BAD_REQUEST", “status_code”:120004}
Reduce the length of the Transaction ID to 50 characters.

Duplicate Transaction ID

This error occurs when the currently shared Transaction ID matches the previous one in the last 5 minutes.

Duplicate Transaction ID {"message": "Duplicate Transaction ID“, "err_code": "BAD_REQUEST", “status_code”:120105} Add a unique Transaction ID.

Invalid Payload

This error occurs when the payload is in incorrect JSON format or when incorrect Channel details are shared.

  • Invalid JSON / Invalid Class
  • Channel Attribute is incorrect / Channel details missing
{"message": "Invalid Payload“, "err_code": "BAD_REQUEST", “status_code”:120006}

Recheck the JSON format and the Channel details.

Sample payload is available on our Info page.

Personalisation Attribute Max length

This error occurs when the Personalization Attribute length is greater than 1500 characters.

  {"message": "Personalisation attribute limit exceeded - {x}“, "err_code": "BAD_REQUEST", “status_code”:120007} Reduce the length of the Personalization Attribute to 1500 characters / payload size of <100 KB

Invalid Recipient

This error occurs when the recipient details like mobile number or email address are invalid.

  {"message": "Invalid Recipient“, "err_code": "BAD_REQUEST", “status_code”:120012} Recheck the recipient details in the API call or the User Profile.

Internal Server Error

This error occurs when MoEngage is not able to resolve the API request.

  {"message": "Unexpected error occurred“, "err_code": "Internal Server Error", “status_code”:140109} Retry using the same API call with a different Transaction ID.

Rate Limit

This error occurs when you cross the Rate Limit.

  {"message": "Too many requests“, "err_code": "Rate Limit", “status_code”:140110} Make API calls within the  Rate Limit.

Payload Errors After Accepting the API Request

Alerts can be configured for parallel/sequential fallback as described below:

  • Parallel: For parallel requests, the payload information of success/failure requests should be added at each channel level.
  • Sequence: For fallback requests, the payload information of success/failure requests should be added for the first channel, and other channels, info should be shared over streams

The list of the payload details that can occur after accepting the API request and the equivalent response codes to be shared under HTTP status code 200/429 for different scenarios across each functionality is given below:

Payload Errors Description Response Codes Resolution
Personalisation Failed This error occurs when the required Personalization attributes are not shared in the API call or User Profile doesn't have these values. {"message": "Successfully Received“, “Request_ID”: 122323, SMS: {"message": "Personalisation Failure - {{attribute name}}“, "err_code": "BAD_REQUEST", “status_code”:120011 / 121011}} Either share the valid Personalization attributes in the API call or update the User Profile with the required values.
Invalid Recipient details This error occurs when the recipient details like mobile number or email address are invalid. {"message": "Successfully Received” , “Request_ID”: 122323, SMS: {"message": "Invalid Recipient“, "err_code": "BAD_REQUEST", “status_code”:120012 / 121012} Recheck the recipient details in the API call or the User Profile.
Internal Errors This error occurs when MoEngage is not able to resolve the API request or channel level details. {"message": "Successfully Received”, “Request_ID”: 122323, SMS: {"message": "Unexpected error occurred“, "err_code": "Internal Server Error", “status_code”:140109 / 141109}} Retry using the same API call.
Vendor Errors



This error occurs when the vendor configuration is invalid.

 

{"message": "Successfully Received”, “Request_ID”: 122323, SMS: {"message": "Invalid Vendor Configuration“, "err_code": "Vendor Error", “status_code”:150013 / 151013}}

Recheck the vendor configuration in MoEngage for SMS, Push, and Email.

This error occurs when the vendor is not available. {"message": "Successfully Received”, “Request_ID”: 122323, SMS: {"message": "Vendor not available“, "err_code": "Vendor Error", “status_code”:150014 / 151014}} NA/MoEngage will retry up to 5 times to submit the message to the vendor.
This error occurs when the vendor rejects the Payload. {"message": "Successfully Received”, “Request_ID”: 122323, SMS: {"message": "Rejected by Vendor with error - {{error from vendor}},“, "err_code": "Vendor Error", “status_code”:150015 / 151015}} Resolve the error sent by the vendor and then make the API call.
This is sent as response when vendor accepts the request {"message": "Successfully Received”, “Request_ID”: 122323, SMS: {"message": "Successfully sent“, "err_code": "NA", “status_code”:200000}}  

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.
  • Error - Live Alert Request received on Sandbox API endpoint
    This error occurs when you hit the live alert ID at the sandbox endpoint. For every alert, there are 2 IDs: one is live, and another is Test; the same behavior can be seen for alerts created on the test environment of the MoEngage Dashboard as well. Test Alert ID can be picked up by editing the Alert and going to the 3rd page.

Previous

Next

Was this article helpful?
3 out of 6 found this helpful

How can we improve this article?