docs.yellow.ai Open in urlscan Pro
2606:4700::6812:669 Public Scan

Back to summary

URL:
https://docs.yellow.ai/docs/platform_concepts/engagement/outbound/notification-engine
Submission: On May 28 via manual (May 28th 2024, 12:59:24 pm UTC) from GB — Scanned from GB

Form analysis
0 forms found in the DOM

Text Content

Help DocsUse Case GuidesAPI ReferenceWhat's New
VideosCommunityTry for free
SearchK

* Get started with yellow.ai
* Studio
* Email automation
* Inbox
* User 360
* Engage
* Engage dashboard
* Outbound templates
* Outbound campaigns
* Create Outbound campaign
* Manage outbound campaigns
* Outbound campaign reports
* Notification API
* Engage best practices
* Flow campaigns
* Inbound campaigns
* Engage FAQs
* Insights
* Channels
* Integrations
* AI Voice bot builder
* Yellow.ai's smart search
* Mobile SDK

*
* Engage
* Outbound campaigns
* Notification API

On this page

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
CodeRegionHostR0Indiahttps://cloud.yellow.aiR1MEAhttps://r1.cloud.yellow.aiR2Jakartahttps://r2.cloud.yellow.aiR3Singaporehttps://r3.cloud.yellow.aiR4USAhttps://r4.cloud.yellow.aiR5Europehttps://r5.cloud.yellow.ai

Headers

HeaderDescription/ValueContent-Typeapplication/jsonx-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

ParameterDatatypeDescriptionbotId*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

ParameterTypeRequiredDescriptionuserDetailsObjectYesDetails of the user to be
notified. Eg. Phone Number for WhatsApp.notification (fields:
params)ObjectYesTemplate detailsmediaObjectOptionalTemplate Media URL, Quick
Reply Payload can be passed hereconfig 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": "abc@xyz.com", //mandatory for email channel
"cc": "cc@xyz.com", //applicable only for email // array of string or string
"bcc": "bcc@xyz.com", //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 codeDescription200Indicates 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 CodeDescription100 - 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 token1004 - 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

For more details, refer to the Meta doc14271 - 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

5.2 IMAGE NOTIFICATION

1. CURL REQUEST

}
}'

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

Previous
Outbound campaign reports
Next
Engage best practices
* 1. Introduction
* 1.1 Features of the Notification API
* 1.2 IPs Whitelisting
* 1.3 Enable Notification API
* 1.4 Send delivery status to Webhook
* 1.5 Send notification API reports
* 2. Notification API Details
* 2.1 Request Information
* 2.2 Sample Webhook Payload
* 2.3 Postman Collections
* 2.4 Response Codes
* 4. Reports
* 5. Examples
* 5.1 Normal Text Notification
* 5.2 Image Notification
* 5.3 File Notification

WAS THE ARTICLE HELPFUL?

Got questions?

docs.yellow.ai Open in urlscan Pro 2606:4700::6812:669 Public Scan

Form analysis 0 forms found in the DOM

Text Content

docs.yellow.ai Open in urlscan Pro
2606:4700::6812:669 Public Scan

Form analysis
0 forms found in the DOM