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 more easy for developers to integrate it anywhere in less time.

To jump to Notification API collections for each channel, see

.

1.1 Features of the Notification API#

  • Single endpoint for multiple channels
  • Enable range of API services with one-click
  • Real-time reports on 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 API Access#

In order 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 and
  3. Click Enable API Access.

Note: If Engage is not enabled, you will get a 400 error (API access is not enabled).

2. Notification API Details#

2.1 Request Information#

Base URL

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

Headers

HeaderDescription/Value
Content-Typeapplication/json
x-api-key* For app.yellow.ai platform: Get the API key from the path Configuration > Access Control > Bot API Key. For cloud.yellow.ai platform: Click the Yellow logo on top left corner > Select your bot from the dropdown > On the top-right corner, click Configure > On the left sidebar, click API Keys (you can see keys only if you are the super admin).

Note: Only users with 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 - To receive delivery updates on clients webhook. Configurable from platform for now.

Please go to Engage > Preferences for setting up the postbackUrl.
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 needs to be sent as a notification. templateId is mandatory.

"notification": {
"templateId": "template_name", // name of the template from template manager// mandatory for WhatsApp, SMS(wherever applicable)
"params": { //renderable parameters defined in the template.
"emiValue": "15000", // variable parameter names as shown on 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": "pricing-ai-chatbot" // over here, "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 Status codes (of response)#

On successful queueing of the notification, you will receive a 202 status code with the relevant msgId. This confirms that the message details has 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 on the reports under Data Explorer on the platform.

CodeDescription
202Message queued successfully. You will receive a msgId for acknowledgement and tracking.
400Bad request. Request structure is not formed correctly. Please check the message field for more information.
401Unauthorised. Please check your auth token. Only Super Admin Auth tokens are accepted for using API.
422Invalid inputs. The request structure is evaluated to be correct but the parameter values are not within 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.

API Error Codes#

CodeDescription
1004 - mediaUploadErrorUTA -- Failed to upload media to whatsapp | wa tier - cloud-api/onprem)
1400 - authExceptionUTA -- If 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 - apiUnknownUTA -- Possibly 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 - apiServiceUTA -- Temporary issue due to downtime. Wait and retry the operation. See Troubleshooting, Error 2 for debugging information. | wa tier - cloud-api/onprem)
1403 - apiMethodUTA -- Capability or permissions issue. Make sure your app has the necessary capability or permissions to make this call. | wa tier - cloud-api/onprem)
1404 - apiTooManyCallsUTA -- Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume. | wa tier - cloud-api/onprem)
1405 - apiPermissionDeniedUTA -- Permission is either not granted or has been removed. Handle the missing permissions. | wa tier - cloud-api/onprem)
1406 - parameterIsInvalidUTA -- One or more parameters are invalid | wa tier - cloud-api/onprem)
1406 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)
1407 - accessTokenExpiredUTA -- Get a new access token. | wa tier - cloud-api/onprem)
1408 - contactsErrorUTA -- Failed to validate contact | wa tier - cloud-api/onprem)
1409 - phoneNumberNotAllowedUTA -- You are not allowed to onboard this phone number in Cloud API, please contact us for more information | wa tier - cloud-api/onprem)
1410 - temporaryBlockForPolicyViolationsUTA -- Wait and retry the operation. | wa tier - cloud-api/onprem)
1411 - duplicatePostUTA -- Duplicate posts cannot be published consecutively. Change the content of the post and try again. | wa tier - cloud-api/onprem)
1412 - platformRateLimitUTA -- You hit platform rate limits, please refer to the Rate Limit section for more information. | wa tier - cloud-api/onprem)
1413 - mediaErrorUTA -- Failed to download the media file used | wa tier - cloud-api/onprem)
1413 - mediaErrorUTA -- Failed to download the media file used | wa tier - cloud-api/onprem)
1414 - paymentIssuesUTA -- There is some issue with the payment method of the Account. Please check on WhatsApp Business Manager if the payment method is set. | wa tier - cloud-api/onprem)
1415 - messageExpiredUTA -- Message failed to send during its Time To Live (TTL) duration. | wa tier - cloud-api/onprem)
1416 - rateLimitErrorUTA -- Message failed to send because there were too many messages sent from this phone number in a short period of time. Resend the failed messages. | wa tier - cloud-api/onprem)
1417 - unsignedCertificateUTA -- Message failed to send because there was an error related to your certificate. Please contact support to investigate | wa tier - cloud-api/onprem)
1418 - reEngagementMessageUTA -- Message failed to send because more than 24 hours have passed since the customer last replied to this number. Use a message template to respond. | wa tier - cloud-api/onprem)
1419 - messagingLimitReachedUTA -- Failed due to WhatsApp 24Hour Limit restrictions. Please check the link to know more: https://developers.facebook.com/docs/whatsapp/api/rate-limits#messaging | wa tier - cloud-api/onprem)
1419 - messagingLimitReachedUTA -- Failed due to WhatsApp 24Hour Limit restrictions. Please check the link to know more: https://developers.facebook.com/docs/whatsapp/api/rate-limits#messaging | wa tier - cloud-api/onprem)
1420 - genericErrorUTA -- WhatsApp was unable to send the message. Please try again. | wa tier - cloud-api/onprem)
1421 - unsuppotredMessageTypeUTA -- Message type is not currently supported | wa tier - cloud-api/onprem)
1422 - messageTooLongUTA -- Message length exceeds 4096 characters. | wa tier - cloud-api/onprem)
1423 - invalidRecepientTypeUTA -- Valid recipient types are: individual | wa tier - cloud-api/onprem)
1424 - accessDeniedUTA -- Number is already registered on WhatsApp See Migrating a Phone Number for information on moving a phone number from WhatsApp to the WhatsApp Business API. | wa tier - cloud-api/onprem)
1425 - resourceNotFoundUTA -- File or resource not found | wa tier - cloud-api/onprem)
1426 - parameterMissingUTA -- Parameter Missing | wa tier - cloud-api/onprem)
1427 - parameterTypeErrorUTA -- Value entered for a parameter is of the wrong type or other problem. | wa tier - cloud-api/onprem)
1428 - badUserUTA -- You will receive this message when you send a message to yourself. To resolve, send the message to a number that is not your own. | wa tier - cloud-api/onprem)
1429 - parameterMissingUTA -- Number of parameters provided does not match the expected number of variable parameters. | wa tier - cloud-api/onprem)
1430 - templateTextTooLongUTA -- Translated text too long | wa tier - cloud-api/onprem)
1431 - formatCharacterPolicyViolatedUTA -- Format character policy violated | wa tier - cloud-api/onprem)
1432 - parameterTypeErrorUTA -- Parameter format does not match format in the created Template. | wa tier - cloud-api/onprem)
1432 - parameterTypeErrorUTA -- Parameter format does not match format in the created Template. | wa tier - cloud-api/onprem)
1433 - incompleteDeleteUTA -- A previous delete operation failed. A delete retry is needed before registering again. | wa tier - cloud-api/onprem)
1434 - decryptionErrorUTA -- Decrypting the backup blob failed for an unknown reason. | wa tier - cloud-api/onprem)
1435 - backupBlobDecryptionErrorUTA -- Backup blob cannot be decrypted due to bad format or bad password.'}, | wa tier - cloud-api/onprem)
1436 - recoveryTokenDecryptionErrorUTA -- Recovery token cannot be decrypted due to bad format or bad password.'}, | wa tier - cloud-api/onprem)
1437 - serverTemporaryUnavailableUTA -- Registration server is temporarily unavailable.'}, | wa tier - cloud-api/onprem)
1438 - securityPinMismatchUTA -- Wrong PIN used. | wa tier - cloud-api/onprem)
1439 - recoveryTokenIncorrectUTA -- The recovery token used for migration is stale. | wa tier - cloud-api/onprem)
1440 - accountBlockedUTA -- Account is blocked by the registration server. | wa tier - cloud-api/onprem)
1441 - tooManyPinGuessesUTA -- Too many PIN guesses for this account. | wa tier - cloud-api/onprem)
1442 - pinGuessedTooFastUTA -- Registration request was made too fast. | wa tier - cloud-api/onprem)
1443 - templateErrorUTA -- Template name does not exist in the translation | wa tier - cloud-api/onprem)
1444 - systemOverloadedUTA -- system overloaded wa cloud api`} | wa tier - cloud-api/onprem)
1500 - messageExpiredUTA -- Message failed to send due to some issue with the WhatsApp Business Account, possibly down or disconnected for more than 1 day | wa tier - cloud-api/onprem)
1501 - ttlLimitReachedUTA -- Message failed to send during its Time To Live (TTL) duration.Resend the message | wa tier - cloud-api/onprem)
14271 - invalidParameterUTA -- One or more parameters are invalid | wa tier - cloud-api/onprem)
14272 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)
14272 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)

2.4 Postman Collections#

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

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

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

Note: Whem you raise any support ticket, include msgId or traceId in the request.

2.5 Response Codes#

Error CodeDescription
1004 - mediaUploadErrorUTA -- Failed to upload media to whatsapp | wa tier - cloud-api/onprem)
1400 - authExceptionUTA -- If 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 - apiUnknownUTA -- Possibly 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 - apiServiceUTA -- Temporary issue due to downtime. Wait and retry the operation. See Troubleshooting, Error 2 for debugging information. | wa tier - cloud-api/onprem)
1403 - apiMethodUTA -- Capability or permissions issue. Make sure your app has the necessary capability or permissions to make this call. | wa tier - cloud-api/onprem)
1404 - apiTooManyCallsUTA -- Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume. | wa tier - cloud-api/onprem)
1405 - apiPermissionDeniedUTA -- Permission is either not granted or has been removed. Handle the missing permissions. | wa tier - cloud-api/onprem)
1406 - parameterIsInvalidUTA -- One or more parameters are invalid | wa tier - cloud-api/onprem)
1406 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)
1407 - accessTokenExpiredUTA -- Get a new access token. | wa tier - cloud-api/onprem)
1408 - contactsErrorUTA -- Failed to validate contact | wa tier - cloud-api/onprem)
1409 - phoneNumberNotAllowedUTA -- You are not allowed to onboard this phone number in Cloud API, please contact us for more information | wa tier - cloud-api/onprem)
1410 - temporaryBlockForPolicyViolationsUTA -- Wait and retry the operation. | wa tier - cloud-api/onprem)
1411 - duplicatePostUTA -- Duplicate posts cannot be published consecutively. Change the content of the post and try again. | wa tier - cloud-api/onprem)
1412 - platformRateLimitUTA -- You hit platform rate limits, please refer to the Rate Limit section for more information. | wa tier - cloud-api/onprem)
1413 - mediaErrorUTA -- Failed to download the media file used | wa tier - cloud-api/onprem)
1413 - mediaErrorUTA -- Failed to download the media file used | wa tier - cloud-api/onprem)
1414 - paymentIssuesUTA -- There is some issue with the payment method of the Account. Please check on WhatsApp Business Manager if the payment method is set. | wa tier - cloud-api/onprem)
1415 - messageExpiredUTA -- Message failed to send during its Time To Live (TTL) duration. | wa tier - cloud-api/onprem)
1416 - rateLimitErrorUTA -- Message failed to send because there were too many messages sent from this phone number in a short period of time. Resend the failed messages. | wa tier - cloud-api/onprem)
1417 - unsignedCertificateUTA -- Message failed to send because there was an error related to your certificate. Please contact support to investigate | wa tier - cloud-api/onprem)
1418 - reEngagementMessageUTA -- Message failed to send because more than 24 hours have passed since the customer last replied to this number. Use a message template to respond. | wa tier - cloud-api/onprem)
1419 - messagingLimitReachedUTA -- Failed due to WhatsApp 24Hour Limit restrictions. Please check the link to know more: https://developers.facebook.com/docs/whatsapp/api/rate-limits#messaging | wa tier - cloud-api/onprem)
1419 - messagingLimitReachedUTA -- Failed due to WhatsApp 24Hour Limit restrictions. Please check the link to know more: https://developers.facebook.com/docs/whatsapp/api/rate-limits#messaging | wa tier - cloud-api/onprem)
1420 - genericErrorUTA -- WhatsApp was unable to send the message. Please try again. | wa tier - cloud-api/onprem)
1421 - unsuppotredMessageTypeUTA -- Message type is not currently supported | wa tier - cloud-api/onprem)
1422 - messageTooLongUTA -- Message length exceeds 4096 characters. | wa tier - cloud-api/onprem)
1423 - invalidRecepientTypeUTA -- Valid recipient types are: individual | wa tier - cloud-api/onprem)
1424 - accessDeniedUTA -- Number is already registered on WhatsApp See Migrating a Phone Number for information on moving a phone number from WhatsApp to the WhatsApp Business API. | wa tier - cloud-api/onprem)
1425 - resourceNotFoundUTA -- File or resource not found | wa tier - cloud-api/onprem)
1426 - parameterMissingUTA -- Parameter Missing | wa tier - cloud-api/onprem)
1427 - parameterTypeErrorUTA -- Value entered for a parameter is of the wrong type or other problem. | wa tier - cloud-api/onprem)
1428 - badUserUTA -- You will receive this message when you send a message to yourself. To resolve, send the message to a number that is not your own. | wa tier - cloud-api/onprem)
1429 - parameterMissingUTA -- Number of parameters provided does not match the expected number of variable parameters. | wa tier - cloud-api/onprem)
1430 - templateTextTooLongUTA -- Translated text too long | wa tier - cloud-api/onprem)
1431 - formatCharacterPolicyViolatedUTA -- Format character policy violated | wa tier - cloud-api/onprem)
1432 - parameterTypeErrorUTA -- Parameter format does not match format in the created Template. | wa tier - cloud-api/onprem)
1432 - parameterTypeErrorUTA -- Parameter format does not match format in the created Template. | wa tier - cloud-api/onprem)
1433 - incompleteDeleteUTA -- A previous delete operation failed. A delete retry is needed before registering again. | wa tier - cloud-api/onprem)
1434 - decryptionErrorUTA -- Decrypting the backup blob failed for an unknown reason. | wa tier - cloud-api/onprem)
1435 - backupBlobDecryptionErrorUTA -- Backup blob cannot be decrypted due to bad format or bad password.'}, | wa tier - cloud-api/onprem)
1436 - recoveryTokenDecryptionErrorUTA -- Recovery token cannot be decrypted due to bad format or bad password.'}, | wa tier - cloud-api/onprem)
1437 - serverTemporaryUnavailableUTA -- Registration server is temporarily unavailable.'}, | wa tier - cloud-api/onprem)
1438 - securityPinMismatchUTA -- Wrong PIN used. | wa tier - cloud-api/onprem)
1439 - recoveryTokenIncorrectUTA -- The recovery token used for migration is stale. | wa tier - cloud-api/onprem)
1440 - accountBlockedUTA -- Account is blocked by the registration server. | wa tier - cloud-api/onprem)
1441 - tooManyPinGuessesUTA -- Too many PIN guesses for this account. | wa tier - cloud-api/onprem)
1442 - pinGuessedTooFastUTA -- Registration request was made too fast. | wa tier - cloud-api/onprem)
1443 - templateErrorUTA -- Template name does not exist in the translation | wa tier - cloud-api/onprem)
1444 - systemOverloadedUTA -- system overloaded wa cloud api`} | wa tier - cloud-api/onprem)
1500 - messageExpiredUTA -- Message failed to send due to some issue with the WhatsApp Business Account, possibly down or disconnected for more than 1 day | wa tier - cloud-api/onprem)
1501 - ttlLimitReachedUTA -- Message failed to send during its Time To Live (TTL) duration.Resend the message | wa tier - cloud-api/onprem)
14271 - invalidParameterUTA -- One or more parameters are invalid | wa tier - cloud-api/onprem)
14272 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)
14272 - invalidUserUTA -- The recipient WhatsApp number is invalid / The user doesn't have a WhatsApp Account | wa tier - cloud-api/onprem)

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.

4. Examples#

4.1 Normal Text Notification#

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

Sample#

drawing

4.2 Image Notification#

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

4.3 File Notification#

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

Sample#