Skip to main content

Notification API

1. Introduction

Yellow.ai's Notification API lets you send business-initiated messages from the various supported channels directly from your CRM or internal Systems.

The API supports different channels (SMS, email, and WhatsApp) and makes it easier for developers to integrate it anywhere in less time.

note

Starting from August 1, 2023, access to Notification APIs has been shifted to an on-demand model. This means that these APIs will no longer be available by default for bots created on or after August 1, 2023.

For a more efficient approach, we strongly recommend adopting Flow campaigns and User Event APIs. Rest assured, bots that were created before August 2023 can still use Notification APIs without any interruptions.

To view Notification API collections for each channel, see

1.1 Features of the Notification API

  • Single endpoint for multiple channels
  • Enable a range of API services with one-click
  • Real-time reports on the YM Platform with the basic features of the BI tool to visualise your data
  • Callback Webhook Configuration support to receive delivery updates directly on your system

1.2 IPs Whitelisting

Additionally, our outbound IPs given below must be whitelisted for the reports callback to flow into your system.

  • 13.71.52.164
  • 13.71.49.46

1.3 Enable Notification API

To use notification APIs, you first need to enable this

To use the Notification API you have to enable it on the platform as explained here:

  1. Go to the Engage module.
  2. Navigate to Preferences.
  3. Click Enable API Access.
note

If notification API is not enabled for the bot, you will get a 400 error (API access is not enabled).

1.4 Send delivery status to Webhook

You can add your webhook to receive delivery status updates in real time along with the custom payload from yellow.ai.

To enable receiving delivery status updates to your webhook:

  1. Go to the Engage module,

  2. Navigate to Preferences.

  3. Enable Postback URL.

  4. In Send the delivery status to (applicable only for notifications API), enter the Webhook URL to which the delivery updates need to be pushed.

    To know what the sample webhook payload looks like, see Sample webhook payload.

note

Ensure that no authentication is required to push data to the Webhook URL.

1.5 Send notification API reports

You can send reports of notifications sent through API to your preferred users. The report is sent as a CSV file for the chosen duration.

To send Notification API reports to your preferred recipients:

  1. Go to the Engage module,

  2. Navigate to Preferences.

  3. Enable Notification API reports.

  4. In Send notification API reports to, enter the email IDs of each recipient to whom you want to send reports. Press Enter after entering each email ID.

  5. In for time period between, set the duration (Start date and End date)for which you want to send the report.

  6. To also send the report of WhatsApp notification API, enable Whatsapp v1 Notification API.

2. Notification API Details

2.1 Request Information

Base URL

https://cloud.yellow.ai/api/engagements/notifications/v2/push?bot={botId}

Region CodeRegionHost
R0Indiahttps://cloud.yellow.ai
R1MEAhttps://r1.cloud.yellow.ai
R2Jakartahttps://r2.cloud.yellow.ai
R3Singaporehttps://r3.cloud.yellow.ai
R4USAhttps://r4.cloud.yellow.ai
R5Europehttps://r5.cloud.yellow.ai

Headers

HeaderDescription/Value
Content-Typeapplication/json
x-api-keyFor https://app.yellow.ai platform: Get the API key from the path Configuration > Access Control > Bot API Key.

For https://cloud.yellow.ai platform: Click on the Access control icon on top-right > Go to API Keys (you can see this option only if you are a bot admin). > Click +Generate API key**. Click here for detailed help.
note

Only users with a Super Admin role can create a Bot API key.

Request Query Parameter

ParameterDatatypeDescription
botId*StringUnique ID of the bot. Login to the Platform and navigate to the bot . You can find the bot ID in the URL Eg: x16387123456

Request Body Parameters

ParameterTypeRequiredDescription
userDetailsObjectYesDetails of the user to be notified. Eg. Phone Number for WhatsApp.
notification (fields: params)ObjectYesTemplate details
mediaObjectOptionalTemplate Media URL, Quick Reply Payload can be passed here
config fields: (customPayload, postbackUrl)Object (Obj, String)OptionalConfiguration details for the API.

customPayload - Custom information will be sent back with delivery updates.

postbackUrl - Used to receive delivery updates on the client's webhook.
To receive delivery updates on the client's webhook, enable Postback URL in Engage > Preferences and enter the Webhook URL. See Send delivery status to webhook.
userDetails Object

This object contains all relevant information about the user. It needs to have at least one contactable information and any number of additional parameters. For a WhatsApp notification, the number field is mandatory.

  "userDetails": {
"number": "919090909090", //mandatory for SMS, WhatsApp, Voice //country code to be added without space // if not added default 91
"email": "[email protected]", //mandatory for email channel
"cc": "[email protected]", //applicable only for email // array of string or string
"bcc": "[email protected]", //applicable only for email // array of string or string
}

notification Object

This contains the message template details that need to be sent as a notification. templateId is mandatory.


{
"notification": {
"templateId": "template_name",
// The name of the template as defined in the template manager. Mandatory for WhatsApp and SMS (wherever applicable).
"params": {
// Renderable parameters defined in the template.
"emiValue": "15000",
// Variable parameter names as shown in the template manager. Dynamic values can be passed,
"balance": "79999",
"media": [
{
// Applicable for WhatsApp.
"title": "title",
// Optional for document media types.
"mediaLink": "https://URL.com.jpeg",
"quickReplies": [
{
"type": "quick_reply",
"value": "payload 1"
},
{
"type": "quick_reply",
"value": "payload 2"
}
]
}
],
"quickReplies": {
"ctaUrlParam": {
"buttonText": "pricing-ai-chatbot"
// "buttonText" represents the text that will be displayed on the button.
// "pricing-ai-chatbot" represents the extension of the URL after the domain (as configured in the template.
}
}
}
}
}


config Object

This contains the list of available pre-configuration that will be validated before sending the messages to the user.

"config": {
"customPayload": {
"firstName": "Wasim",
"phone": "91999999999",
"UID" : "Got the details"
},
"postbackUrl": "https://webhook.url"
}

2.2 Sample Webhook Payload

As soon as we receive a callback from the downstream services, we will post that data to the configured Webhook if available. Webhooks will be called with the request body.

{
"event": {
"status": "delivered"
},
"userId": "919999999999",
"source": "whatsapp",
"campaign": "apiNotifications",
"templateId": "video_button1",
"msgId": "3Yp8jdIUj8jNeoFOP1ZLT",
"workflowId": null,
"firstName": "Wasim",
"phone": "91999999999",
"UID": "Got the details"
}

2.3 Postman Collections

To access the entire Postman documentation and run collections, click the following button.

For API details of a specific channel, click the respective channel.

  1. WhatsApp
  2. SMS
  3. Email
  4. Bulk messaging API
note

When you raise any support ticket, include msgId or traceId in the request.

2.4 Response Codes

On successful queueing of the notification, you will receive a 202 status code with the relevant msgId. This confirms that the message details have been received by us and will be queued for sending on the relevant channel. The downstream service will pick the queue and will start sending it and updating the delivery status on the webhook, and the reports under Data Explorer on the platform.

HTTP Response Codes

Status codeDescription
200Indicates general success of an API call.
201Indicates successful resource creation.
202Message queued successfully. You will receive a msgId for acknowledgement and tracking.
204Response payload is empty.
301Should be used to relocate resources. New URI should be used in the Location header of the response.
400Bad request. Request structure is not formed correctly. Please check the message field for more information.
401Unauthorised or invalid access token. Please check your auth token. Only Super Admin Auth tokens are accepted for using API.
403Unauthorized user.
404Resource not found.
405HTTP method not supported for the API.
406Must be used when the requested media type cannot be served by the API.
415Rquest body does not contain content type.
422Invalid inputs. The request structure is evaluated to be correct but the parameter values are not within the expected range. Channel not configured.
429Rate limited. Occurs when there are too many requests sent to the API within a short time. Once a rate limit error is captured, the rate of the API call should be decreased to honour the limits. Default Rate Limit is 2000 requests/min per Bot.
500Internal server error. TraceId will be sent back for tracking.
503Downstream service is temporarily unavailable. Please try again later.

API Error Codes

Error CodeDescription
100 - Parameter is invalidOne or more parameters are invalid. Please check the error message to learn more about how to fix it.
190 - Access token has expiredGenerate a new access token
1004 - mediaUploadErrorFailed to upload media to WhatsApp (wa tier - cloud-api/onprem)
1400 - authExceptionIf no sub-code is present, the login status or access token has expired, been revoked, or is otherwise invalid. Get a new access token. If a sub-code is present, see the subcode. (wa tier - cloud-api/onprem)
1401 - apiUnknownPossibly a temporary issue due to downtime. Wait and retry the operation. If it occurs again, check that you are requesting an existing API. See Authentication and Authorization Errors for debugging information. (wa tier - cloud-api/onprem)
1402 - apiServiceTemporary issue due to downtime. Wait and retry the operation. See Troubleshooting, Error 2 for debugging information. (wa tier - cloud-api/onprem)
1403 - apiMethodCapability or permissions issue. Make sure your app has the necessary capability or permissions to make this call. (wa tier - cloud-api/onprem)
1404 - apiTooManyCallsTemporary issue due to throttling. Wait and retry the operation, or examine your API request volume. (WA tier - cloud-api/onprem)
1405 - apiPermissionDeniedPermission is either not granted or has been removed. Handle the missing permissions. (WA tier - cloud-api/onprem)
1406 - parameterIsInvalidOne or more parameters are invalid (wa tier - cloud-api/onprem)
1406 - invalidUserThe recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account (wa tier - cloud-api/onprem)
1407 - accessTokenExpiredGet a new access token. (WA tier - cloud-api/onprem)
1408 - contactsErrorClient-side rate limit has been hit. Unable to deliver message. Reasons can include:
The recipient phone number is not a WhatsApp phone number.
  1. Recipient has not accepted our new Terms of Service and Privacy Policy.
  2. Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:
    - Android: 2.21.15.15
    - SMBA: 2.21.15.15
    - iOS: 2.21.170.4
    - SMBI: 2.21.170.4
    - KaiOS: 2.2130.10
    - Web: 2.2132.6
  3. The message was not delivered to create a high quality user experience. See Per-User Marketing Template Message
1409 - phoneNumberNotAllowedYou are not allowed to onboard this phone number in Cloud API, please contact us for more information (wa tier - cloud-api/onprem)
1410 - temporaryBlockForPolicyViolationsThe WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy (wa tier - cloud-api/onprem).
1411 - duplicatePostDuplicate posts cannot be published consecutively. Change the content of the post and try again. (wa tier - cloud-api/onprem)
1412 - platformRateLimitYou hit platform rate limits, please refer to the Rate Limit section for more information. (wa tier - cloud-api/onprem)
1413 - Media download errorMessage failed to send because there were one or more errors related to your payment method.
- Payment account is not attached to a WhatsApp Account.
- Credit line is over the limit.
- Credit line (Payment account) not set or active.
- WhatsApp Business Account is deleted.
- Account has been suspended by us.
- Timezone not set.
- Currency not set.
- MessagingFor request (On Behalf Of (OBO)) is pending or declined.
- Check your payment setup in WhatsApp Manager and try again. (wa tier - cloud-api/onprem)
1414 - paymentIssuesThere is some issue with the payment method of the Account. Please check on WhatsApp Business Manager.
1415 - Message expiredMessage failed to send during its Time To Live (TTL) duration.
1416 - Rate limit errorMessage failed to send because there were too many messages sent from this phone number in a short period of time. Please resend the failed messages.
1417 - Unsigned certificateMessage failed to send because there was an error related to your certificate. Please contact support to investigate.
1418 - Reengagement messageMessage failed to send because more than 24 hours have passed since the customer last replied to this number. Use a message template to respond.
1419 - Messaging limit reachedFailed due to WhatsApp 24-Hour Limit restrictions. Please check the link to know more about the restrictions.
1420 - Generic errorWhatsApp was unable to send the message. Please try again.
1421 - Unsupported message typeMessage type is not supported. Please use the right message type.
1422 - Message too longMessage length exceeds the limit of 4096 characters. Please shorten the message and try again.
1423 - Invalid recipient type-
1424 - Access deniedNumber is already registered on WhatsApp. See Migrating a Phone Number for information on moving a phone number from WhatsApp to the WhatsApp Business API.
1425 - Resource not foundFile or resource is not found.
1426 - Parameter is missingRequired parameter is missing.
1427 - parameterTypeErrorThe value entered for a parameter is of the wrong type or there is another problem.
1428 - badUserYou will receive this message when you send a message to yourself. To resolve this, please send the message to a number that is not your own.
1429 - parameterMissingNumber of parameters passed does not match the expected number of variable parameters.
1432 - parameterTypeErrorThe format of the parameter does not match with the format in the created template.
1443 - Template errorTemplate name does not exist in the translation.
1444 - System overloadedWhatsApp cloud API system is overloaded.
1500 - messageExpiredThe message failed to send due to some issue with the WhatsApp Business Account. It may be down or disconnected for more than 1 day.
1501 - ttlLimitReachedThe message failed to send during its Time To Live (TTL) duration. Please resend the message.
1504 - waCompatibilityThere could be any of the following reasons:
  • Unable to deliver message due to software/device compatibility.
  • The recipient's phone number is not a WhatsApp phone number.
  • Recipient has not accepted our new Terms of Service and Privacy Policy.
  • Recipients using an old WhatsApp version; must use the following WhatsApp version or greater:
    - Android: 2.21.15.15
    - SMBA: 2.21.15.15
    - iOS: 2.21.170.4
    - SMBI: 2.21.170.4
    - KaiOS: 2.2130.10
    - Web: 2.2132.6
14271 - invalidParameterOne or more parameters are invalid. (WA tier - cloud-api/onprem).
14272 - Invalid userThe recipient WhatsApp number is invalid or the user doesn't have a WhatsApp account.
130472 - UndeliverableFailed to send message because this user's phone number is part of an experiment.
note

When using Notification APIs, you may encounter the following error message if a WhatsApp template receives a low rating.

{ 
success: false,
message: "Template:<template-name> has reached low quality and cannot be used"
}

4. Reports

You can view data regarding the campaigns you execute through the Insights module.

  1. Within Insights, select the Data Explorer tab on the left.
  2. In the Data Explorer section, select Notification Reports under Default Datasets.
  3. To begin experimenting with Campaign Reports, you can select Filters, and use filters such as BOTID, CAMPAIGNID, and TEMPLATEID individually, or in different combinations to pull data.
  4. Once you have generated a data set that you find useful, click on Summarise. With this, you can group and summarise this data set in different ways.

5. Examples

5.1 Normal Text Notification

1. CURL request

curl --location --request POST 'https://app.yellowmessenger.com/api/engagements/notifications/v2/push?bot=BOT_ID_HERE' \
--header 'x-auth-token: TOKEN' \
--header 'Content-Type: application/json' \
--header 'Cookie: ym_xid=TOKEN' \
--data-raw '{
"userDetails": {
"number": "USER_PHONE_NUMBER"
},
"notification": {
"type": "whatsapp",
"sender": "SENDER_PHONE_NUMBER",
"templateId": "TEMPLATE_ID",
"params": {
"1": "var1",
"2": "www.yellow.ai"
}
}
}'

2. Sample

drawing

5.2 Image Notification

1. CURL request

curl --location --request POST 'https://app.yellowmessenger.com/api/engagements/notifications/v2/push?bot=BOT_ID_HERE' \
--header 'x-auth-token: TOKEN' \
--header 'Content-Type: application/json' \
--header 'Cookie: ym_xid=TOKEN' \
--data-raw '{
"userDetails": {
"number": "USER_PHONE_NUMBER"
},
"notification": {
"type": "whatsapp",
"sender": "SENDER_PHONE_NUMBER",
"templateId": "TEMPLATE_ID",
"params": {
"media": {
"mediaLink": "MEDIA_URL"
},
"1": "var1",
"2": "www.yellow.ai",
"3": "test"
}

}
}'

5.3 File Notification

1. CURL request

curl --location --request POST 'https://app.yellowmessenger.com/api/engagements/notifications/v2/push?bot=BOT_ID_HERE' \
--header 'x-auth-token: TOKEN' \
--header 'Content-Type: application/json' \
--header 'Cookie: ym_xid=TOKEN' \
--data-raw '{
"userDetails": {
"number": "USER_PHONE_NUMBERs"
},
"notification": {
"type": "whatsapp",
"sender": "SENDER_PHONE_NUMBER",
"templateId": "TEMPLATE_ID",
"params": {
"media": {
"mediaLink": "MEDIA_URL"
},
"1": "var1",
"2": "www.yellow.ai",
"3": "test"
}

}
}'

2. Sample