Supported Scenarios
Transactional Alerts are designed for critical user communications, including:- 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
- Send a transactional message on a single channel like SMS or Email or Push.
- Send transactional messages on multiple channels.
Endpoint
The Inform API consists of the following endpoint:Glossary
The following is a list of terminology that you will encounter when using the Inform API.| Term | Definition |
|---|---|
| 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 vs. Test Environments
Ensure you are using the correct ID and Endpoint for your environment.
| Feature | Live Alerts | Test Alerts |
|---|---|---|
| Identifier | Use the Alert ID for published alerts. | Use the Test Alert ID for testing. |
| Logs | Logs are available in the Alert Info section. | Logs are available in the 3rd Step of Alert Creation. |
| Endpoint | https://api-0{dc}.moengage.com | https://sandbox-api-0{dc}.moengage.com |
How Does Inform API Work and Respond?
Reach out to your Customer Success Manager to enable sending the channel level details as part of your API response.
- A check is performed to verify if the API request received for Inform is valid.
- If valid, the second process is to resolve the content and send a message using the partner.
Response Codes
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.
| Category Code | Details |
|---|---|
| 1 | Unauthorized |
| 2 | Bad Request |
| 4 | Internal Server Error / Ratelimit |
| 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 | {"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": "DUPLICATE_REQUEST_RECEIVED", "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.
| 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 with a different Transaction ID. |
| 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. |
| Vendor Unavailable | 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. |
| Vendor Rejected | 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. |
| Vendor Accepted | 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}} | - |
FAQs
How are duplicate requests handled?
How are duplicate requests handled?
A request is deemed a duplicate in the following cases:
- It is received within 5 minutes of a previously successful request containing the same transaction_id
- It is received within 5 minutes of a previous request which is ‘In Progress’ (being processed) and contains the same transaction_id
What happens when a vendor does not accept requests from MoEngage?
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?
Are Alert Logs stored in MoEngage?
Alert logs are stored for up to 30 days for every Alert in MoEngage.
Why is this error occuring "Live Alert Request received on Sandbox API endpoint"?
Why is this error occuring "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.