{"id":18046,"date":"2018-05-04T07:47:19","date_gmt":"2018-05-04T07:47:19","guid":{"rendered":"https:\/\/developer.kore.ai\/v8-0\/?post_type=docs&#038;p=13873"},"modified":"2021-03-25T16:15:31","modified_gmt":"2021-03-25T16:15:31","slug":"adding-webhook-channel","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v8-0\/docs\/bots\/channel-enablement\/adding-webhook-channel\/","title":{"rendered":"Adding WebHook as a channel"},"content":{"rendered":"<section class=\"l-section wpb_row height_auto\"><div class=\"l-section-h i-cf\"><div class=\"g-cols vc_row type_default valign_top\"><div class=\"vc_col-sm-12 wpb_column vc_column_container\"><div class=\"vc_column-inner\"><div class=\"wpb_wrapper\">\r\n\t<div class=\"wpb_text_column \">\r\n\t\t<div class=\"wpb_wrapper\">\r\n\t\t\t<p>Webhook channel provides a generic webhook integration to connect your bot with any external communication systems. Kore.ai platform provides standard request and response APIs to be used to send and receive text messages. End user\u2019s input through a voice, keypad, or any other means needs to be converted to plain text before it is sent to the Kore.ai platform using the request API.<\/p>\n<p><strong>NOTE<\/strong>: From ver 7.0 you can enable multiple WebHook channels to your Bot, once added the WebHook channel will not be disabled from the Channel list and you can use the same process to enable another WebHook channel with a different name. The webhook channels with name and type mentioned (webhook ) will be available at channels filter at the dashboard and analyze section to views the metrics on the applied channel. You will be able to apply channel-specific overrides for each of the webhook channels created\/enabled &#8211; channel selection drop will show all the webhook channels created. Further, all the channels will be available for selection during the Bot deployment.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Pre-requisites\"><strong>Pre-requisites<\/strong><\/span><\/h2>\n<p>To enable the Webhook channel for your Kore.ai bot, you need to:<\/p>\n<ol>\n<li><b>Associate App-<\/b>-To enable the Webhook channel for your Kore.ai bot, you need to associate the channel with either an existing app in your Kore.ai account or create a new app.<\/li>\n<li><b> Select Integration Mode- <\/b> You will need to enable an integration mode that is supported by the channel based on your business requirement. You can copy the Webhook URL from the configurations tab of the channel.<\/li>\n<li><b> Review Payload Formats- <\/b> Review Payload formats for verifying the integration.<\/li>\n<\/ol>\n<p>To access Bot Platform\u2019s public APIs, the application making the API request requires authentication. Kore.ai uses the JWT (JSON Web Token) technology to handle the authentication. For a quick overview of the JWT token, read <a href=\"https:\/\/jwt.io\/introduction\/\">Introduction to JWT tokens<\/a>.<\/p>\n<h2><span class=\"ez-toc-section\" id=\"Configuring_Webhook_as_a_channel\"><b>Configuring Webhook as a channel<\/b><\/span><\/h2>\n<ol>\n<li>In the <b>Bots<\/b> section of the Bot Builder, click the Bot to which you want to add the Webhook channel.<\/li>\n<li>On the <b>Channels<\/b> tab, click the <b>Webhook<\/b> icon. The <b>Webhook<\/b> page gets displayed.<br \/><a ref=\"magnificPopup\" href=\"\/wp-content\/uploads\/sites\/16\/webhook_channel.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-17531\" src=\"\/wp-content\/uploads\/sites\/16\/webhook_channel.png\" alt=\"\" width=\"820\" height=\"461\" \/><\/a><\/li>\n<li>Navigate to <b>Configurations<\/b> tab of this page and associate this channel with an app.<\/li>\n<li>Give a\u00a0<strong>Name<\/strong> to the Channel.<\/li>\n<li>You may select any of the existing <strong>Apps<\/strong> available in your Kore.ai account or create a new app.<\/li>\n<li>Enter a name for the app and click Create. The app gets created and <strong>Client ID<\/strong> and <strong>Client Secret<\/strong> is generated. Copy the Client ID and Client Secret details.<\/li>\n<li>Webhook channel supports both <strong>synchronous<\/strong> and <strong>asynchronous<\/strong> modes and depending on your business needs, you can enable one of these modes in the Configurations tab.\n<ul>\n<li><strong>Synchronous mode<\/strong> delivers full response directly to the incoming requests. Note: Alert can not be set up webhook on webhook channel in synchronous mode, you may want to consider using the onAlert event through BotKit, <a href=\"\/docs\/bots\/sdks\/sdk-events\/#OnAlert\" target=\"_blank\" rel=\"noopener noreferrer\">refer here for details<\/a>.<\/li>\n<li><strong>Asynchronous mode<\/strong>\u00a0defines the POST_URL of your external system and Access Token to be used for delivering partial or full responses. When hit, the WebHook URL will receive an empty message with 200 status code, the response message will be sent to the POST_URL defined.<\/li>\n<\/ul>\n<\/li>\n<li><span style=\"font-weight: 400\">Select <\/span><b>Yes <\/b><span style=\"font-weight: 400\">to<\/span><b> Enable Channel.<\/b><\/li>\n<li><strong>Save<\/strong> the configuration. The Webhook URL at this channel instance will be created dynamically.<\/li>\n<li>Use the <strong>Webhook URL<\/strong> to establish integration with external communication systems. <strong>This URL will be available only after enabling the channel<\/strong>.<br \/><a ref=\"magnificPopup\" href=\"\/wp-content\/uploads\/sites\/16\/webhook_config.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-17532\" src=\"\/wp-content\/uploads\/sites\/16\/webhook_config.png\" alt=\"\" width=\"820\" height=\"461\" \/><\/a><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400\">After completion of these steps, a success message appears on the screen, and a channel request is sent to your Bots Admin for approval. <\/span><\/p>\n<p><b>Notes<\/b><span style=\"font-weight: 400\">: <\/span><\/p>\n<ul>\n<li><span style=\"font-weight: 400\">The channel remains non-functional until the Bots Admin approves it.<\/span><\/li>\n<li>In the case of Bot Import, WebHook channels will also be imported. You would need to configure the channels which are created with the import and associate the channels with an application.<\/li>\n<li>In the case of Smart Bots, if the parent has webhook channels configured, these channels will be inherited to the child bots. The channel is inheritance happens to child bot every time a new webhook channel is added at the parent and published.<\/li>\n<\/ul>\n<h3><span class=\"ez-toc-section\" id=\"WebHook_API_Reference\"><b><span style=\"font-weight: 400\">WebHook API Reference<\/span><\/b><\/span><\/h3>\n<p><span style=\"font-weight: 400\">Receives plain text messages from external communication systems<\/span><\/p>\n<ul>\n<li>in case of single webhook configuration and in case of multi-webhook configuration for the first instance\n<pre>POST \u00a0{{host_url}}<i>\/chatbot\/hooks\/{{bot<\/i> id}}<\/pre>\n<\/li>\n<li>in case of multi-webhook configuration for the second instance onwards:\n<pre>POST  {{host_url}}\/chatbot\/hooks\/{{bot<i> id}}\/hookInstance\/{{webHookId}} <\/i><\/pre>\n<\/li>\n<\/ul>\n<h5><span style=\"font-weight: 400\">Query Parameters<\/span><\/h5>\n<table>\n<tbody>\n<tr>\n<td><b>Parameter<\/b><\/td>\n<td><b>Description<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400\">host_url<\/span><\/td>\n<td><span style=\"font-weight: 400\">Your Kore.ai Bots Platform URL.<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400\">bot id<\/span><\/td>\n<td><span style=\"font-weight: 400\">The ID of the bot to which you want to post messages. You can access it from the General Settings page of the bot.<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h5><span style=\"font-weight: 400\">Authorization<\/span><\/h5>\n<p><span style=\"font-weight: 400\">Invoke the API with JWT in the header with the following syntax:<\/span><\/p>\n<pre>Authorization<span style=\"font-weight: 400\">: bearer {{JWT}}<\/span><\/pre>\n<p><span style=\"font-weight: 400\">Generate JWT using the following header and payload <a href=\"\/tools\/jwt\/\" target=\"_blank\" rel=\"noopener noreferrer\">from this page<\/a>.<\/span><\/p>\n<p><b>JWT Header<\/b><\/p>\n<pre>{\r\n  \"alg\": \"HS256\",\r\n  \"typ\": \"JWT\"\r\n }<\/pre>\n<p><b>JWT Payload<\/b><\/p>\n<pre>{\r\n  \"appId\": \"{{clientId of the bot}}\",\r\n  \"sub\" : \"{{random number}}\"\r\n  }<\/pre>\n<p><b>Note<\/b>: JWT should be generated and signed by the secret key from the server(backend). JWT should not be generated in the browser. The Secret Key should be kept in the server.<\/p>\n<h5><span style=\"font-weight: 400\">Response content type<\/span><\/h5>\n<pre>application\/json<\/pre>\n<h5><span style=\"font-weight: 400\">Sample Payload Reference<\/span><\/h5>\n<pre>payload : {\r\n           \"message\":{\r\n             \"text\" : \"Hi\",\r\n             \"attachments\" : [&lt;array of attachment links&gt;]\r\n            },\r\n           \"from\" :{\r\n             \"id\": &lt;unique-id-of-sender(mandatory)&gt;\r\n            },\r\n          \"mergeIdentity\" :&lt;true\/false&gt;,\r\n          \"preferredChannelForResponse\":\"&lt;channel name&gt;\" \/\/the channel context to be used to generate a response   \r\n          }<\/pre>\n<h5>Sample cURL<\/h5>\n<pre>curl -X POST\r\n{{host}}\/chatbot\/hooks\/{{bot-id}}\r\n\/\/{{host_url}}\/chatbot\/hooks\/{{bot id}}\/hookInstance\/{{webHookId}} in case of multi-webhook configuration\r\n -H 'authorization: bearer {{JWT Token}}'\r\n -H 'content-type: application\/json'\r\n -d '{ \"message\": { \r\n          \"text\": \"hi\" }, \r\n       \"from\": { \r\n          \"id\": \"1323465\" }, \r\n       \"mergeIdentity\" :true,\r\n        \"preferredChannelForResponse\":\"rtm\"\r\n     }'<\/pre>\n<h5><span style=\"font-weight: 400\">Synchronous Response<\/span><\/h5>\n<pre>{\r\n  \"text\" : \"message\"\r\n  }<\/pre>\n<p><span style=\"font-weight: 400\">If the response that needs to sent back is of a template, then the template JSON object will be included in the text array object. <a href=\"\/docs\/bots\/advanced-topics\/kore-web-sdk\/message-templates\/\">Refer here for more on message templates.<\/a><\/span><\/p>\n<h5>Asynchronous Response<\/h5>\n<p>When the client app sends the request to Webhook URL configured in Asynchronous mode, the platform responds back with an empty message and a status code 200.<\/p>\n<p><a ref=\"magnificPopup\" href=\"https:\/\/kore-wordpress.s3.us-east-2.amazonaws.com\/developer.kore.ai\/wp-content\/uploads\/sites\/16\/20221201100036\/webhook_async_response.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-full wp-image-17534\" src=\"https:\/\/kore-wordpress.s3.us-east-2.amazonaws.com\/developer.kore.ai\/wp-content\/uploads\/sites\/16\/20221201100036\/webhook_async_response.png\" alt=\"\" width=\"820\" height=\"91\" \/><\/a><\/p>\n<p>&nbsp;<\/p>\n<p>Further, the platform sends the response to the POST_URL configured at the channel based on the request received from the client app.<\/p>\n<p>Following is the format of the response sent to the POST_URL. <span style=\"font-weight: 400\">If the response that needs to sent back is of a template, then the template JSON object will be included in the text array object. <a href=\"\/docs\/bots\/advanced-topics\/kore-web-sdk\/message-templates\/\">Refer here for more on message templates.<\/a><\/span><\/p>\n<pre>{\r\n \"text\" : \"message\",\r\n \"from\" : \"from_id\",\r\n \"mergeIdentity\" :&lt;true\/false&gt;\r\n }\r\n<\/pre>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n<div class=\"w-separator size_small with_line width_default thick_1 style_solid color_border align_center\"><div class=\"w-separator-h\"><\/div><\/div>\r\n\t<div class=\"wpb_text_column \">\r\n\t\t<div class=\"wpb_wrapper\">\r\n\t\t\t<h2><span class=\"ez-toc-section\" id=\"Handling_Digital_Forms\">Handling Digital Forms<\/span><\/h2>\n<p>If your bot has a form that needs user input, for synchronous WebHook channel would be getting the complete form definition in the response and you need to send the formData in the request when interacting with the bot.<\/p>\n<h4>Sample Response<\/h4>\n<pre>{\r\n    \"text\": [],\r\n    \"form\": {\r\n        \"formDef\": { Formdef },\r\n        \"formInitialization\": { FormInitialization } \/\/if any\r\n    }\r\n    ..other params if any\r\n}<\/pre>\n<p><strong>FormDef<\/strong><br \/>\n(This is the complete Form definition which is used to render the Form)<\/p>\n<pre>{\r\n  \"_id\": \"\",\r\n  \"refId\": \"\",\r\n  \"streamId\": \"st-####a#d-##fd-#b##-acab-b#f#f######\",\r\n  \"branding\": { \r\n     \"properties\": []\r\n    },\r\n  \"components\": [\r\n    {\r\n     \"_id\": \"fct-#f#e###d-d#b#-###a-#a##-######f###b\",\r\n     \"refId\": \"#####f##-###c-###b-##a#-da########1d\",\r\n     \"metaData\": {\r\n         \"type\": \"textField\",\r\n         \"key\": \"textField\",\r\n         \"displayName\": \"Text Field\",\r\n         \"name\": \"TextField0\",\r\n         \"placeholder\": \"Provide your input\",\r\n         \"toolTip\": \"\",\r\n         \"isVisible\": true,\r\n         \"required\": false,\r\n         \"validations\": {\r\n            \"validationType\": \"simple\"\r\n            },\r\n         \"validateOn\": \"onBlur\"\r\n      },\r\n     \"name\": \"TextField0\",\r\n     \"type\": \"textField\"\r\n  },\r\n  {\r\n    \"_id\": \"fct-#f#e###d-d#b#-###a-#a##-######f###b\",\r\n    \"refId\": \"#####f##-###c-###b-##a#-da########1d\",\r\n    \"metaData\": {\r\n       \"type\": \"textField\",\r\n       \"key\": \"textField\",\r\n       \"displayName\": \"Text Field\",\r\n       \"name\": \"TextField1\",\r\n       \"placeholder\": \"Provide your input\",\r\n       \"toolTip\": \"\",\r\n       \"isVisible\": true,\r\n       \"required\": false,\r\n       \"validations\": {\r\n          \"validationType\": \"simple\"\r\n         },\r\n       \"validateOn\": \"onBlur\"\r\n      },\r\n      \"name\": \"TextField1\",\r\n      \"type\": \"textField\"\r\n    },\r\n   {\r\n     \"_id\": \"fct-#f#e###d-d#b#-###a-#a##-######f###b\", \r\n     \"refId\": \"#####f##-###c-###b-##a#-da########1d\",\r\n     \"metaData\": {\r\n        \"key\": \"button\",\r\n        \"type\": \"button\",\r\n        \"displayName\": \"Submit\",\r\n        \"name\": \"Submit\",\r\n        \"buttonAction\": \"submit\",\r\n        \"isVisible\": true,\r\n        \"buttonStyle\": \"primary\",\r\n        \"sourceUrl\": \"\"\r\n       },\r\n     \"name\": \"Submit\",\r\n     \"type\": \"button\"\r\n     }\r\n    ],\r\n   \"description\": \"regular\",\r\n   \"displayName\": \"Form 1\",\r\n   \"name\": \"firstForm\",\r\n   \"type\": \"regular\", \r\n   (... few other fields)\r\n}<\/pre>\n<p><strong>FormInitialization<\/strong><br \/>\n(This should be used for pre-filling Forms)<\/p>\n<pre>{\r\n       \"valueMap\": {\r\n       \"TextField0\": \"input1\",\r\n       \"TextField1\": \"input2\"\r\n      }\r\n}<\/pre>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n\r\n\t<div class=\"wpb_text_column \">\r\n\t\t<div class=\"wpb_wrapper\">\r\n\t\t\t<h4>Sample Request<\/h4>\n<pre>{\r\n    \"session\": {\r\n        \"new\": false\r\n    },\r\n    \"message\": {\r\n        \"formData\": {\r\n            \"formId\": \"frm-2b2f1ae4-9a3b-5f22-8940-b6827710940f\",\r\n            \"data\": [\r\n                {\r\n                    \"componentId\": \"fct-9f7e487d-d4b8-542a-9a77-7806819f141b\",\r\n                    \"input\": \"input1\"\r\n                },\r\n                {\r\n                    \"componentId\": \"fct-7aae4eae-2ce7-5d1b-8db1-bb5cfadc3342\",\r\n                    \"input\": \"input2\"\r\n                }\r\n            ],\r\n            \"meta\": {}\r\n        }\r\n    },\r\n    \"from\": {\r\n        \"id\": \"\"\r\n    }\r\n    ..others params if any\r\n}\r\n<\/pre>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n<div class=\"w-separator size_small with_line width_default thick_1 style_solid color_border align_center\"><div class=\"w-separator-h\"><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/section>\n","protected":false},"excerpt":{"rendered":"Webhook channel provides a generic webhook integration to connect your bot with any external communication systems. Kore.ai platform provides standard request and response APIs to be used to send and receive text messages. End user\u2019s input through a voice, keypad, or any other means needs to be converted to plain text before it is sent...","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-18046","post","type-post","status-publish","format-standard","hentry","category-channel-enablement"],"_links":{"self":[{"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/posts\/18046","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/comments?post=18046"}],"version-history":[{"count":20,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/posts\/18046\/revisions"}],"predecessor-version":[{"id":24902,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/posts\/18046\/revisions\/24902"}],"wp:attachment":[{"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/media?parent=18046"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/categories?post=18046"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-0\/wp-json\/wp\/v2\/tags?post=18046"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}