{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c35a1e5f-1c91-41ac-a7c4-f7f8d6d866c3","name":"Notification API (V2)","description":"Yellow.ai's Notification API lets you send any Business-Initiated messages from the various supported channels directly from your CRM or Internal System.\n\nThe API supports different channels (SMS, email, and WhatsApp) making it more easy for developers to integrate it anywhere in less time.\n\n#### Key features of the Notification API :\n\n*   Single endpoint for multiple channels\n*   Enable range of API services with one-click\n*   Real-time reports on YM Platform with the basic features of the BI tool to visualise your data\n*   Callback Webhook Configuration support to receive delivery updates directly on your system\n    \n\n#### Enable API Access:\n\nIn order to use the Notification API you have to enable it on the platform as explained here\n\n1.  Go to the **Engage** module,\n2.  Navigate to **Preferences** and\n3.  Click **Enable API Access**.\n    \n\n***Note***: If Engage is not enabled, you will get a `400` error with the message `API access is not enabled`.\n\n#### Request Information\n\n**Base URL:**\n\n`https://cloud.yellow.ai/api/engagements/notifications/v2/push?bot={botId}`\n\n**Headers:**\n\n| **Header** | **Description/Value** |\n| --- | --- |\n| `Content-Type` | application/json |\n| `x-api-key` | * **For** **`app.yellow.ai`** **platform**: Get the API key from the path **Configuration** > **Access Control** > **Bot API Key**.  <br>* **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). |\n\n> **Note**: Only users with Super Admin role can create a Bot API key.\n\n#### Request Query Parameter\n\n| **Parameter** | **Datatype** | **Description** |\n| --- | --- | --- |\n| botId* | String | Unique ID of the bot. Login to the Platform and navigate to the bot . You can find the bot ID in the URL Eg: x16387123456 |\n\n#### Request Body Parameters\n\n| **Parameter** | **Type** | **Required** | **Description** |\n| --- | --- | --- | --- |\n| `userDetails` | Object | Yes | Details of the user to be notified. Eg. Phone Number for WhatsApp. |\n| `notification`  <br>fields: `params` | Object  <br>Object | Yes | Template details |\n| `media` | Object | Optional | Template Media URL, Quick Reply Payload can be passed here |\n| `config`fields: `customPayload`, `postbackUrl` | Object  <br>Object, String | Optional | Configuration details for the API  <br>`customPayload`: Custom info. Will be sent back with delivery updates.  <br>`postbackUrl`: To receive delivery updates on clients webhook. Configurable from platform for now. Please go to Engage>Preferences for setting up the `postbackUrl.` |\n\n#### **`userDetails`** **Object**\n\n`userDetails` may contain 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.\n\n``` json\n  \"userDetails\": {\n       \"number\": \"919090909090\", //mandatory for SMS, WhatsApp, Voice     //country code to be added without space // if not added default 91\n       \"email\": \"abc@xyz.com\", //mandatory for email channel\n       \"cc\": \"cc@xyz.com\", //applicable only for email // array of string or string\n       \"bcc\": \"bcc@xyz.com\", //applicable only for email // array of string or string\n   }\n\n```\n\n#### **`notification`** **Object**\n\n`notification` contains the message template details that needs to be sent as a notification. `templateId` is mandatory.\n\n``` json\n\"notification\": {\n    \"templateId\": \"template_name\", // name of the template from template manager// mandatory for WhatsApp, SMS(wherever applicable)\n    \"params\": { //renderable parameters defined in the template.\n           \"emiValue\": \"15000\", // variable parameter names as shown on template manager. Dynamic values can be passed.\n           \"balance\": \"79999\",\n           \"media\": [{ //applicable for whatsapp // \n                       \"title\": \"title\", //optional for document media types\n                       \"mediaLink\": \"https://URL.com.jpeg\",\n                       \"quickReplies\": [\n                                {\n                                    \"type\": \"quick_reply\",\n                                    \"value\": \"payload 1\"\n                                },\n                                {\n                                    \"type\": \"quick_reply\",\n                                    \"value\": \"payload 2\"\n                                }\n                            ]\n                     }],\n           \"quickReplies\": {\n                \"ctaUrlParam\": \"pricing-ai-chatbot\" // over here, \"pricing-ai-chatbot\" represents the extension of the URL after the domain (as configured in the template)\n           }\n\n```\n\n#### `config` Object\n\nconfig contains the list of available pre-configuration that will be validated before sending the messages to the user.\n\n``` json\n\"config\": {\n        \"customPayload\": {\n            \"firstName\": \"Wasim\",\n            \"phone\": \"91999999999\",\n            \"UID\" : \"Got the details\"\n        },\n       \"postbackUrl\": \"https://webhook.url\"\n   }\n\n```\n\n#### Sample Webhook Payload\n\nAs 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.\n\n``` json\n{\n  \"event\": {\n    \"status\": \"delivered\"\n  },\n  \"userId\": \"919999999999\",\n  \"source\": \"whatsapp\",\n  \"campaign\": \"apiNotifications\",\n  \"templateId\": \"video_button1\",\n  \"msgId\": \"3Yp8jdIUj8jNeoFOP1ZLT\",\n  \"workflowId\": null,\n  \"firstName\": \"Wasim\",\n  \"phone\": \"91999999999\",\n  \"UID\": \"Got the details\"\n}\n\n```\n\n#### **Response status codes**\n\nOn successful queueing of the notification, you will receive a 202 status code with the 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.\n\n| **HTTP Status Code** | **Description** |\n| --- | --- |\n| 202 | Message queued successfully. You will receive a msgId for acknowledgement and tracking. |\n| 400 | Bad request. Request structure is not formed correctly. Please check the `message` field for more information. |\n| 401 | Unauthorised. Please check your auth token. Only Super Admin Auth tokens are accepted for using API. |\n| 422 | Invalid inputs. The request structure is evaluated to be correct but the parameter values are not within expected range. Channel not configured. |\n| 429 | Rate 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.  <br>***Default Rate Limit is 2000 requests/min per Bot.*** |\n| 500 | Internal server error. TraceId will be sent back for tracking. |\n\n##### Whitelisting of IPs:\n\nAdditionally, our outbound IPs given below must be whitelisted for the reports callback to flow into your system.\n\n*   13.71.52.164\n*   13.71.49.46\n    \n\n#### Reports\n\nYou can view data regarding the campaigns you execute through the **Insights** module.\n\n1.  Within **Insights**, select the **Data Explorer** tab on the left.\n2.  In the **Data Explorer** section, select **Notification Reports** under **Default Datasets.**\n3.  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.\n4.  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.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"9982063","collectionId":"c35a1e5f-1c91-41ac-a7c4-f7f8d6d866c3","publishedId":"UzBvGPGB","public":true,"publicUrl":"https://documenter-api.postman.tech/view/9982063/UzBvGPGB","privateUrl":"https://go.postman.co/documentation/9982063-c35a1e5f-1c91-41ac-a7c4-f7f8d6d866c3","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.6","publishDate":"2022-06-30T08:08:35.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/UzBvGPGB"}