{"_id":"5845a4aa9f6fbb1b00430844","version":{"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","__v":2,"createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0","592deb23644f060f008e5aa6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"category":{"_id":"5845a4a89f6fbb1b004307bf","__v":0,"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-26T17:19:04.989Z","from_sync":false,"order":7,"slug":"guidelines","title":"Guidelines"},"parentDoc":null,"project":"54d3007669578e0d002730c9","user":"55bf6cdcad601c2b00762d13","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-03T01:40:57.488Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"* [Overview](#overview)\n* [Task](#task)\n* [Create Entity for Shipping Zones](#create-entity-for-shipping-zones)\n* [Modify “shipping.cost” Intent](#modify-shippingcost-intent)\n* [Create a Web Service](#create-a-web-service)\n* [Deploy the Web Service](#deploy-the-web-service)\n* [Enable Webhook in API.AI](#enable-webhook-in-apiai)\n* [Test Your Agent](#test-your-agent)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThis example shows one of many ways to design your agent so that it can respond depending on parameter values using the <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">API.AI Webhook integration</a>.\n\nWe suggest that you read the <a href=\"https://docs.api.ai/docs/guidelines-online-store-support-agent\" target=\"_blank\">article about creating Online Store Support agent</a> first.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Task\"\n}\n[/block]\nLet’s imagine that our <a href=\"https://docs.api.ai/docs/guidelines-online-store-support-agent\" target=\"_blank\">Online Store Support agent</a> should provide information about shipping prices for different regions. Here’s our pricing table:\n[block:html]\n{\n  \"html\": \"  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\"><strong>Region</strong></div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell\\\"><strong>Shipping Price</strong></div>\\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Europe</div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell cell-right\\\">100</div>\\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">North America</div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell cell-right\\\">200</div>\\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">South America</div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell cell-right\\\">300</div>\\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Asia</div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell cell-right\\\">400</div>\\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Africa</div>\\n    <div class=\\\"col-md-3 col-sm-6 col-xs-12 cell cell-right\\\">500</div>\\n  </div>\\n\\n\\n<style>\\n\\n  .cell {\\n\\t\\t\\tborder-bottom: 1px solid #ddd;\\n     \\tpadding:10px;\\n    \\tpadding-left: 10px;\\n  }\\n  \\n  .cell-left {\\n    \\tmargin-left: 10px;\\n    \\tpadding: 10px;\\n  }\\n  \\n  .cell-right {\\n    \\tpadding-left: 40px;\\n  \\n  }\\n\\n</style>\"\n}\n[/block]\nIt wouldn’t be convenient to store this information in your agent – you’d have to create 5 different intents to provide 5 different responses.\n\nInstead, you can store the data in your own database and let your agent access it through a web service via an <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">API.AI Webhook integration</a>.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Entity for Shipping Zones\"\n}\n[/block]\nWe’ll create an entity “shipping-zone” in order to extract parameter values corresponding to world regions.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/638c665-shipping-zone-entity.png\",\n        \"shipping-zone-entity.png\",\n        1999,\n        727,\n        \"#318dc8\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Modify “shipping.cost” Intent\"\n}\n[/block]\nWe add some examples with shipping zones to the existing “shipping.cost” intent. The “shipping-zone” parameter should automatically appear in the parameter table. Check the ‘Required’ checkbox and add a prompt to choose from 5 shipping zones.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7b67228-online-store-shipping-cost-intent.png\",\n        \"online-store-shipping-cost-intent.png\",\n        2072,\n        1400,\n        \"#f7f7f7\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nIf a user asks a general question about shipment like *“Is shipping expensive?”*, the agent will request more information, namely, to choose one of the 5 shipping regions in order to answer the user’s specific question.\n\nFor more information about required parameters, see the documentation on <a href=\"https://docs.api.ai/docs/dialogs\" target=\"_blank\">Slot Filling</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create a Web Service\"\n}\n[/block]\nLet’s create a web service using a mircoframework for Python called <a href=\"http://flask.pocoo.org\" target=\"_blank\">Flask</a>. \n\nThe web service should meet all the requirements described here: <a href=\"https://docs.api.ai/docs/webhook#webhook-requirements\" target=\"_blank\">https://docs.api.ai/docs/webhook#webhook-requirements</a>.\n\nFor illustration purposes, <a href=\"https://github.com/svet4/shipping-costs-sample/blob/master/app.py\" target=\"_blank\">our web service example</a> will be very simple. Instead of creating a real database, we’ll simulate one with a Python dictionary that maps the shipping zones to the shipping costs. \n\n```cost = {'Europe':100, 'North America':200, 'South America':300, 'Asia':400, 'Africa':500}```\n\nHow to design the database is entirely up to you. For example, instead of these world regions, you could use country names as a criteria for providing the shipping price information.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Deploy the Web Service\"\n}\n[/block]\nTo deploy our web service, we’ll use <a href=\"https://www.heroku.com\" target=\"_blank\">Heroku</a>. You can use any other service or your own server.\n\nIf you want to try it with your agent on Heroku, sign into your Heroku account and click the 'Deploy to Heroku' button here: <a href=\"https://github.com/svet4/shipping-costs-sample\" target=\"_blank\">https://github.com/svet4/shipping-costs-sample</a>.\n\nOn the Heroku page that will open, create a name for your app and click 'Deploy for Free'.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/54fdda2-Online-support-shipping-Heroku.png\",\n        \"Online-support-shipping-Heroku.png\",\n        2372,\n        1432,\n        \"#7f63a8\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Enable Webhook in API.AI\"\n}\n[/block]\nGo to ‘Fulfillment’ from the left side menu in your agent, enable the Webhook integration, insert the link `https://[App Name].herokuapp.com/webhook` to the URL field, and click ‘Save’.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3b2a600-online-store-support.png\",\n        \"online-store-support.png\",\n        2046,\n        1266,\n        \"#fafafa\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nGo to the “shipping.cost” intent, check ‘Use webhook’ in the ‘Fulfillment’ section, and save the intent.\n\nYou can leave a generic response in the ‘Response’ section. It’ll be given if the web service is unavailable or returns errors.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7854033-online-support-enable-webhook-intent.png\",\n        \"online-support-enable-webhook-intent.png\",\n        2088,\n        1398,\n        \"#f9f9f9\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Test Your Agent\"\n}\n[/block]\nNow we can test our agent. Here’s how it can look if you test it via the <a href=\"https://docs.api.ai/docs/agent-demo-page\" target=\"_blank\">agent demo page</a>:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/30716d0-test-webhook-for-online-store.gif\",\n        \"test-webhook-for-online-store.gif\",\n        408,\n        536,\n        \"#2d343c\"\n      ]\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"webhook-for-online-store-support-agent","type":"basic","title":"Webhook Example for Online Store Support Agent"}

Webhook Example for Online Store Support Agent


* [Overview](#overview) * [Task](#task) * [Create Entity for Shipping Zones](#create-entity-for-shipping-zones) * [Modify “shipping.cost” Intent](#modify-shippingcost-intent) * [Create a Web Service](#create-a-web-service) * [Deploy the Web Service](#deploy-the-web-service) * [Enable Webhook in API.AI](#enable-webhook-in-apiai) * [Test Your Agent](#test-your-agent) [block:api-header] { "type": "basic", "title": "Overview" } [/block] This example shows one of many ways to design your agent so that it can respond depending on parameter values using the <a href="https://docs.api.ai/docs/webhook" target="_blank">API.AI Webhook integration</a>. We suggest that you read the <a href="https://docs.api.ai/docs/guidelines-online-store-support-agent" target="_blank">article about creating Online Store Support agent</a> first. [block:api-header] { "type": "basic", "title": "Task" } [/block] Let’s imagine that our <a href="https://docs.api.ai/docs/guidelines-online-store-support-agent" target="_blank">Online Store Support agent</a> should provide information about shipping prices for different regions. Here’s our pricing table: [block:html] { "html": " <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\"><strong>Region</strong></div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell\"><strong>Shipping Price</strong></div>\n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Europe</div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell cell-right\">100</div>\n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">North America</div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell cell-right\">200</div>\n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">South America</div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell cell-right\">300</div>\n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Asia</div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell cell-right\">400</div>\n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Africa</div>\n <div class=\"col-md-3 col-sm-6 col-xs-12 cell cell-right\">500</div>\n </div>\n\n\n<style>\n\n .cell {\n\t\t\tborder-bottom: 1px solid #ddd;\n \tpadding:10px;\n \tpadding-left: 10px;\n }\n \n .cell-left {\n \tmargin-left: 10px;\n \tpadding: 10px;\n }\n \n .cell-right {\n \tpadding-left: 40px;\n \n }\n\n</style>" } [/block] It wouldn’t be convenient to store this information in your agent – you’d have to create 5 different intents to provide 5 different responses. Instead, you can store the data in your own database and let your agent access it through a web service via an <a href="https://docs.api.ai/docs/webhook" target="_blank">API.AI Webhook integration</a>. [block:api-header] { "type": "basic", "title": "Create Entity for Shipping Zones" } [/block] We’ll create an entity “shipping-zone” in order to extract parameter values corresponding to world regions. [block:image] { "images": [ { "image": [ "https://files.readme.io/638c665-shipping-zone-entity.png", "shipping-zone-entity.png", 1999, 727, "#318dc8" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "basic", "title": "Modify “shipping.cost” Intent" } [/block] We add some examples with shipping zones to the existing “shipping.cost” intent. The “shipping-zone” parameter should automatically appear in the parameter table. Check the ‘Required’ checkbox and add a prompt to choose from 5 shipping zones. [block:image] { "images": [ { "image": [ "https://files.readme.io/7b67228-online-store-shipping-cost-intent.png", "online-store-shipping-cost-intent.png", 2072, 1400, "#f7f7f7" ], "sizing": "full" } ] } [/block] If a user asks a general question about shipment like *“Is shipping expensive?”*, the agent will request more information, namely, to choose one of the 5 shipping regions in order to answer the user’s specific question. For more information about required parameters, see the documentation on <a href="https://docs.api.ai/docs/dialogs" target="_blank">Slot Filling</a>. [block:api-header] { "type": "basic", "title": "Create a Web Service" } [/block] Let’s create a web service using a mircoframework for Python called <a href="http://flask.pocoo.org" target="_blank">Flask</a>. The web service should meet all the requirements described here: <a href="https://docs.api.ai/docs/webhook#webhook-requirements" target="_blank">https://docs.api.ai/docs/webhook#webhook-requirements</a>. For illustration purposes, <a href="https://github.com/svet4/shipping-costs-sample/blob/master/app.py" target="_blank">our web service example</a> will be very simple. Instead of creating a real database, we’ll simulate one with a Python dictionary that maps the shipping zones to the shipping costs. ```cost = {'Europe':100, 'North America':200, 'South America':300, 'Asia':400, 'Africa':500}``` How to design the database is entirely up to you. For example, instead of these world regions, you could use country names as a criteria for providing the shipping price information. [block:api-header] { "type": "basic", "title": "Deploy the Web Service" } [/block] To deploy our web service, we’ll use <a href="https://www.heroku.com" target="_blank">Heroku</a>. You can use any other service or your own server. If you want to try it with your agent on Heroku, sign into your Heroku account and click the 'Deploy to Heroku' button here: <a href="https://github.com/svet4/shipping-costs-sample" target="_blank">https://github.com/svet4/shipping-costs-sample</a>. On the Heroku page that will open, create a name for your app and click 'Deploy for Free'. [block:image] { "images": [ { "image": [ "https://files.readme.io/54fdda2-Online-support-shipping-Heroku.png", "Online-support-shipping-Heroku.png", 2372, 1432, "#7f63a8" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "basic", "title": "Enable Webhook in API.AI" } [/block] Go to ‘Fulfillment’ from the left side menu in your agent, enable the Webhook integration, insert the link `https://[App Name].herokuapp.com/webhook` to the URL field, and click ‘Save’. [block:image] { "images": [ { "image": [ "https://files.readme.io/3b2a600-online-store-support.png", "online-store-support.png", 2046, 1266, "#fafafa" ], "sizing": "full" } ] } [/block] Go to the “shipping.cost” intent, check ‘Use webhook’ in the ‘Fulfillment’ section, and save the intent. You can leave a generic response in the ‘Response’ section. It’ll be given if the web service is unavailable or returns errors. [block:image] { "images": [ { "image": [ "https://files.readme.io/7854033-online-support-enable-webhook-intent.png", "online-support-enable-webhook-intent.png", 2088, 1398, "#f9f9f9" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "basic", "title": "Test Your Agent" } [/block] Now we can test our agent. Here’s how it can look if you test it via the <a href="https://docs.api.ai/docs/agent-demo-page" target="_blank">agent demo page</a>: [block:image] { "images": [ { "image": [ "https://files.readme.io/30716d0-test-webhook-for-online-store.gif", "test-webhook-for-online-store.gif", 408, 536, "#2d343c" ] } ] } [/block]