{"__v":0,"_id":"5845a4aa9f6fbb1b00430843","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307bf","__v":0,"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","version":{"__v":1,"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-09T22:23:57.327Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"This article will give a quick overview on how to get started working on an online store support agent. Before you start reading, <a href=\"https://s3.amazonaws.com/static.api.ai/agents/OnlineStoreSupport.zip\" target=\"_blank\">download</a> and <a href=\"https://docs.api.ai/docs/concept-agents#section-restore\" target=\"_blank\">import</a> the sample agent, if you haven’t already.\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n* [Benefits](#benefits)\n* [Overview ](#overview)\n* [Create Agent](#create-agent)\n* [Create Intents](#create-intents)\n* [Test Intents](#test-intents)\n* [Create Entities](#create-entities)\n* [Create Fallback Intent](#create-fallback-intent)\n* [Create Responses](#create-responses)\n* [Use Contexts](#use-contexts)\n* [Integrate with your app, website, or bot](#integrate-with-your-app-website-or-bot)\n* [Related Topics](#related-topics)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Benefits\"\n}\n[/block]\nFirst, let’s highlight all the benefits of adding conversational capabilities to your support pages and bots:\n\n1. Your real support agents won’t have to deal with as many repetitive questions — the most frequent requests will be handled by their artificial sidekick.\n\n2. The automated agent will cover the real ones at inconvenient shifts like nights, lunches, vacations, public holidays, rush hours, or just lazy hours.\n\n3. Having more free time available for more important and creative tasks, your human support agents can spend that time working with more complicated tasks or creating interaction scenarios for the artificial support agent. Or maybe work on something else.\n\n4. Having instant answers to their questions, your customers will be much happier.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThe agent we’re going to talk about in this article is designed to automatically reply to the most common questions to an imaginary online store customer support about shipping, return policy, and order status. Of course, this is a demo agent and the most frequent questions for your company will be different. Its goal is to give you an idea on how to create a smart automatic support agent using API.AI tools.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Agent\"\n}\n[/block]\nStart by <a href=\"https://console.api.ai/api-client/#/newAgent\" target=\"_blank\">creating an agent</a>. Ours is called OnlineStoreSupport.\n\nIf you choose to use our demo agent, here are the  <a href=\"https://docs.api.ai/docs/concept-agents#section-restore\" target=\"_blank\">instructions</a> on how to import it into your account.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Intents\"\n}\n[/block]\nBefore you do anything, outline a few main questions you want to start with. This will help you to structure the agent.\n\nAn <a href=\"https://docs.api.ai/docs/concept-intents\" target=\"_blank\">intent</a> in your agent represents a mapping between what a user says and what action should be taken by your product. Every intent you create should correspond to one question. In the intents you will write all the different ways of how those questions may be phrased by your customers. Don’t worry, you won’t have to write all of them. We’re using machine learning to train your agent to understand a lot more variations based on the examples you provide in intents.\n\nNow we’re ready to create our first intent. From anywhere in the console, click the plus button next to 'Intents' in the left side menu. If you’re in the Intents tab already, click the 'Create Intent'  button.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/81a6689-OnlineStore-create-intent.png\",\n        \"OnlineStore-create-intent.png\",\n        2058,\n        716,\n        \"#2c84b6\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nWe will call our first intent \"shipping.locations\". It will capture questions about locations that our online store delivers to. We already have a few examples of questions in there. Note that while you’re writing examples in the 'User Says' section, the system will try to <a href=\"https://docs.api.ai/docs/concept-intents#section-example-annotation\" target=\"_blank\">annotate</a> them automatically to extract the relevant information from your customer requests. If you don’t like the way your examples are annotated, you can change it any time you want. You can change the entities used, parameter names, and the part of the annotated phrase. Or perhaps you want to <a href=\"https://docs.api.ai/docs/concept-intents#section-automatic-annotation\" target=\"_blank\">remove the annotation</a> altogether.\n\nGive the <a href=\"https://docs.api.ai/docs/concept-intents#action\" target=\"_blank\">action</a> a name, so the request has something to map to. In our example, the action name will be the same as the intent name – \"shipping.locations\". You can choose any name you like.\n\nIf there is no special logic that needs to be applied to provide a <a href=\"https://docs.api.ai/docs/concept-intents#response\" target=\"_blank\">response</a>, you can write it right here in the intent. That’s what we did.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/929f150-OnlineStore-intent.gif\",\n        \"OnlineStore-intent.gif\",\n        652,\n        573,\n        \"#ebedee\"\n      ]\n    }\n  ]\n}\n[/block]\nLooks like we’ve covered everything. Click 'Save' and our first intent is ready. It takes a couple of seconds to train the machine learning model for your agent with the new information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Test Intents\"\n}\n[/block]\nNow let’s test our first intent. Even on the small training set like the one we have here, our agent recognizes a lot of other variations pretty well.\n\nWhile testing your agent in the <a href=\"https://docs.api.ai/docs/get-started#step-4-test-and-train-your-agent\" target=\"_blank\">test console</a>, you can see how your requests are recognized and what responses are given. You can see the JSON with details right there too.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c7ddc1d-OnlineStore-test.gif\",\n        \"OnlineStore-test.gif\",\n        355,\n        582,\n        \"#dbdee0\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Entities\"\n}\n[/block]\nThe \"shipping.location\" intent used only system <a href=\"https://docs.api.ai/docs/concept-entities\" target=\"_blank\">entities</a>. These are entities that the API.AI team created for you, so you don’t have to. If you don’t find an entity you need, you can create <a href=\"https://docs.api.ai/docs/concept-entities#section-developer-entities\" target=\"_blank\">yours</a>.\n\nYou can do it by clicking the plus button next to 'Entities' in the left side menu. If you’re in the list of entities, click the 'Create Entity' button.\n\nIn our agent we used 2 types of entities. \n\n<a href=\"https://docs.api.ai/docs/concept-entities#section-developer-mapping-entities\" target=\"_blank\">Developer mapping entities</a> are basic entities, where you list entries and synonyms for them. In our agent, they are `:::at:::payment-method` and `@return-reason`. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6a980f3-OnlineStore-payment-method.png\",\n        \"OnlineStore-payment-method.png\",\n        2064,\n        902,\n        \"#3086bd\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n<a href=\"https://docs.api.ai/docs/concept-entities#section-developer-composite-entities\" target=\"_blank\">Composite entities</a> can contain other entities. When you create a composite entity untick the ‘Define synonyms’ option and list entities (or combinations of entities) with the name of their alias after `:` (e.g., `@sys.geo-city:city`). See the `@location` entity.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bcda0a4-OnlineStore-location-entity.png\",\n        \"OnlineStore-location-entity.png\",\n        2056,\n        694,\n        \"#2f88c1\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Fallback Intent\"\n}\n[/block]\nNow we have intents that help our store understand what the guests are asking. We also need a way to understand requests that the agent is not trained for yet. For this purpose, we added a <a href=\"https://docs.api.ai/docs/concept-intents#fallback-intent\" target=\"_blank\">fallback intent</a>. It’s a special intent that matches all the requests that don’t match by other intents.\n\nThe same way as regular intents it can return an action of your choice, so you could form a response. You can also write responses in the 'Text response' field.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Create Responses\"\n}\n[/block]\nThere are a few ways of how you can deliver responses to your customers:\n\n1. Write  <a href=\"https://docs.api.ai/docs/concept-intents#response\" target=\"_blank\">responses</a> directly in the intents, just like we did in our demo agent. This is the simplest way, which is convenient if no conditional logic is required to form the responses. Basically, it’s good for Q&A types of agents.\n\n2. Use a <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">webhook</a> to connect to your business logic. See an example <a href=\"https://docs.api.ai/docs/webhook-for-online-store-support-agent\" target=\"_blank\">here</a>.\n\n3. Use one of the <a href=\"https://docs.api.ai/docs/sdks\" target=\"_blank\">SDK’s</a> to send requests and get responses from our API.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Use Contexts\"\n}\n[/block]\n<a href=\"https://docs.api.ai/docs/concept-contexts\" target=\"_blank\">Context</a> is a very powerful feature which you can use to build a conversation scenario with multiple follow-up questions, pass parameter values from one request to another, or use information from your app, device, or your user profile to help your business logic form the best response.\n\nWe used contexts to understand follow-up requests. Let’s look at the \"return.policy\" intent. It understands various ways how people request information on our return policy. We expect some follow-up requests when our customers specify why they may want to return an item.\n\nTo understand that the follow-up requests are related to the initial question, we created an output context \"return-policy\" in the initial intent. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b63f251-OnlineStore-output-context.png\",\n        \"OnlineStore-output-context.png\",\n        2052,\n        732,\n        \"#2c8cbf\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nThen we create another intent “return-policy - reason”, which will catch only follow-up requests like *“What if I broke it?”*, *“Actually it was damaged.”*, and so on. To make it work only after the initial requests, we use the \"return-policy\" context as an input context. This way the examples and their variations that we use in this intent only work when the \"return-policy\" context is active.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4eed3c7-OnlineStore_input_context.png\",\n        \"OnlineStore_input_context.png\",\n        2014,\n        738,\n        \"#2d8abd\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nRead more about contexts in the <a href=\"https://docs.api.ai/docs/concept-contexts\" target=\"_blank\">docs</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Integrate with your app, website, or bot\"\n}\n[/block]\nOur agent has learned to understand people and answer in a proper manner, so the real support agents could pick up the conversations that were beyond our agent’s capabilities. Now, it’s time to integrate it into your app, bot, or website. Your agent can be easily integrated in all major platforms. Have a look at the complete list integrations and SDK’s <a href=\"https://console.api.ai/api-client/#/agent//integrations\" target=\"_blank\">here</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Related Topics\"\n}\n[/block]\n- <a href=\"https://docs.api.ai/docs/webhook-for-online-store-support-agent\" target=\"_blank\">Webhook Example for Online Store Support Agent</a>","excerpt":"","slug":"guidelines-online-store-support-agent","type":"basic","title":"Online Store Support Demo Agent"}

Online Store Support Demo Agent


This article will give a quick overview on how to get started working on an online store support agent. Before you start reading, <a href="https://s3.amazonaws.com/static.api.ai/agents/OnlineStoreSupport.zip" target="_blank">download</a> and <a href="https://docs.api.ai/docs/concept-agents#section-restore" target="_blank">import</a> the sample agent, if you haven’t already. [block:api-header] { "type": "basic" } [/block] * [Benefits](#benefits) * [Overview ](#overview) * [Create Agent](#create-agent) * [Create Intents](#create-intents) * [Test Intents](#test-intents) * [Create Entities](#create-entities) * [Create Fallback Intent](#create-fallback-intent) * [Create Responses](#create-responses) * [Use Contexts](#use-contexts) * [Integrate with your app, website, or bot](#integrate-with-your-app-website-or-bot) * [Related Topics](#related-topics) [block:api-header] { "type": "basic", "title": "Benefits" } [/block] First, let’s highlight all the benefits of adding conversational capabilities to your support pages and bots: 1. Your real support agents won’t have to deal with as many repetitive questions — the most frequent requests will be handled by their artificial sidekick. 2. The automated agent will cover the real ones at inconvenient shifts like nights, lunches, vacations, public holidays, rush hours, or just lazy hours. 3. Having more free time available for more important and creative tasks, your human support agents can spend that time working with more complicated tasks or creating interaction scenarios for the artificial support agent. Or maybe work on something else. 4. Having instant answers to their questions, your customers will be much happier. [block:api-header] { "type": "basic", "title": "Overview" } [/block] The agent we’re going to talk about in this article is designed to automatically reply to the most common questions to an imaginary online store customer support about shipping, return policy, and order status. Of course, this is a demo agent and the most frequent questions for your company will be different. Its goal is to give you an idea on how to create a smart automatic support agent using API.AI tools. [block:api-header] { "type": "basic", "title": "Create Agent" } [/block] Start by <a href="https://console.api.ai/api-client/#/newAgent" target="_blank">creating an agent</a>. Ours is called OnlineStoreSupport. If you choose to use our demo agent, here are the <a href="https://docs.api.ai/docs/concept-agents#section-restore" target="_blank">instructions</a> on how to import it into your account. [block:api-header] { "type": "basic", "title": "Create Intents" } [/block] Before you do anything, outline a few main questions you want to start with. This will help you to structure the agent. An <a href="https://docs.api.ai/docs/concept-intents" target="_blank">intent</a> in your agent represents a mapping between what a user says and what action should be taken by your product. Every intent you create should correspond to one question. In the intents you will write all the different ways of how those questions may be phrased by your customers. Don’t worry, you won’t have to write all of them. We’re using machine learning to train your agent to understand a lot more variations based on the examples you provide in intents. Now we’re ready to create our first intent. From anywhere in the console, click the plus button next to 'Intents' in the left side menu. If you’re in the Intents tab already, click the 'Create Intent' button. [block:image] { "images": [ { "image": [ "https://files.readme.io/81a6689-OnlineStore-create-intent.png", "OnlineStore-create-intent.png", 2058, 716, "#2c84b6" ], "sizing": "full" } ] } [/block] We will call our first intent "shipping.locations". It will capture questions about locations that our online store delivers to. We already have a few examples of questions in there. Note that while you’re writing examples in the 'User Says' section, the system will try to <a href="https://docs.api.ai/docs/concept-intents#section-example-annotation" target="_blank">annotate</a> them automatically to extract the relevant information from your customer requests. If you don’t like the way your examples are annotated, you can change it any time you want. You can change the entities used, parameter names, and the part of the annotated phrase. Or perhaps you want to <a href="https://docs.api.ai/docs/concept-intents#section-automatic-annotation" target="_blank">remove the annotation</a> altogether. Give the <a href="https://docs.api.ai/docs/concept-intents#action" target="_blank">action</a> a name, so the request has something to map to. In our example, the action name will be the same as the intent name – "shipping.locations". You can choose any name you like. If there is no special logic that needs to be applied to provide a <a href="https://docs.api.ai/docs/concept-intents#response" target="_blank">response</a>, you can write it right here in the intent. That’s what we did. [block:image] { "images": [ { "image": [ "https://files.readme.io/929f150-OnlineStore-intent.gif", "OnlineStore-intent.gif", 652, 573, "#ebedee" ] } ] } [/block] Looks like we’ve covered everything. Click 'Save' and our first intent is ready. It takes a couple of seconds to train the machine learning model for your agent with the new information. [block:api-header] { "type": "basic", "title": "Test Intents" } [/block] Now let’s test our first intent. Even on the small training set like the one we have here, our agent recognizes a lot of other variations pretty well. While testing your agent in the <a href="https://docs.api.ai/docs/get-started#step-4-test-and-train-your-agent" target="_blank">test console</a>, you can see how your requests are recognized and what responses are given. You can see the JSON with details right there too. [block:image] { "images": [ { "image": [ "https://files.readme.io/c7ddc1d-OnlineStore-test.gif", "OnlineStore-test.gif", 355, 582, "#dbdee0" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Create Entities" } [/block] The "shipping.location" intent used only system <a href="https://docs.api.ai/docs/concept-entities" target="_blank">entities</a>. These are entities that the API.AI team created for you, so you don’t have to. If you don’t find an entity you need, you can create <a href="https://docs.api.ai/docs/concept-entities#section-developer-entities" target="_blank">yours</a>. You can do it by clicking the plus button next to 'Entities' in the left side menu. If you’re in the list of entities, click the 'Create Entity' button. In our agent we used 2 types of entities. <a href="https://docs.api.ai/docs/concept-entities#section-developer-mapping-entities" target="_blank">Developer mapping entities</a> are basic entities, where you list entries and synonyms for them. In our agent, they are `@payment-method` and `@return-reason`. [block:image] { "images": [ { "image": [ "https://files.readme.io/6a980f3-OnlineStore-payment-method.png", "OnlineStore-payment-method.png", 2064, 902, "#3086bd" ], "sizing": "full" } ] } [/block] <a href="https://docs.api.ai/docs/concept-entities#section-developer-composite-entities" target="_blank">Composite entities</a> can contain other entities. When you create a composite entity untick the ‘Define synonyms’ option and list entities (or combinations of entities) with the name of their alias after `:` (e.g., `@sys.geo-city:city`). See the `@location` entity. [block:image] { "images": [ { "image": [ "https://files.readme.io/bcda0a4-OnlineStore-location-entity.png", "OnlineStore-location-entity.png", 2056, 694, "#2f88c1" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "basic", "title": "Create Fallback Intent" } [/block] Now we have intents that help our store understand what the guests are asking. We also need a way to understand requests that the agent is not trained for yet. For this purpose, we added a <a href="https://docs.api.ai/docs/concept-intents#fallback-intent" target="_blank">fallback intent</a>. It’s a special intent that matches all the requests that don’t match by other intents. The same way as regular intents it can return an action of your choice, so you could form a response. You can also write responses in the 'Text response' field. [block:api-header] { "type": "basic", "title": "Create Responses" } [/block] There are a few ways of how you can deliver responses to your customers: 1. Write <a href="https://docs.api.ai/docs/concept-intents#response" target="_blank">responses</a> directly in the intents, just like we did in our demo agent. This is the simplest way, which is convenient if no conditional logic is required to form the responses. Basically, it’s good for Q&A types of agents. 2. Use a <a href="https://docs.api.ai/docs/webhook" target="_blank">webhook</a> to connect to your business logic. See an example <a href="https://docs.api.ai/docs/webhook-for-online-store-support-agent" target="_blank">here</a>. 3. Use one of the <a href="https://docs.api.ai/docs/sdks" target="_blank">SDK’s</a> to send requests and get responses from our API. [block:api-header] { "type": "basic", "title": "Use Contexts" } [/block] <a href="https://docs.api.ai/docs/concept-contexts" target="_blank">Context</a> is a very powerful feature which you can use to build a conversation scenario with multiple follow-up questions, pass parameter values from one request to another, or use information from your app, device, or your user profile to help your business logic form the best response. We used contexts to understand follow-up requests. Let’s look at the "return.policy" intent. It understands various ways how people request information on our return policy. We expect some follow-up requests when our customers specify why they may want to return an item. To understand that the follow-up requests are related to the initial question, we created an output context "return-policy" in the initial intent. [block:image] { "images": [ { "image": [ "https://files.readme.io/b63f251-OnlineStore-output-context.png", "OnlineStore-output-context.png", 2052, 732, "#2c8cbf" ], "sizing": "full" } ] } [/block] Then we create another intent “return-policy - reason”, which will catch only follow-up requests like *“What if I broke it?”*, *“Actually it was damaged.”*, and so on. To make it work only after the initial requests, we use the "return-policy" context as an input context. This way the examples and their variations that we use in this intent only work when the "return-policy" context is active. [block:image] { "images": [ { "image": [ "https://files.readme.io/4eed3c7-OnlineStore_input_context.png", "OnlineStore_input_context.png", 2014, 738, "#2d8abd" ], "sizing": "full" } ] } [/block] Read more about contexts in the <a href="https://docs.api.ai/docs/concept-contexts" target="_blank">docs</a>. [block:api-header] { "type": "basic", "title": "Integrate with your app, website, or bot" } [/block] Our agent has learned to understand people and answer in a proper manner, so the real support agents could pick up the conversations that were beyond our agent’s capabilities. Now, it’s time to integrate it into your app, bot, or website. Your agent can be easily integrated in all major platforms. Have a look at the complete list integrations and SDK’s <a href="https://console.api.ai/api-client/#/agent//integrations" target="_blank">here</a>. [block:api-header] { "type": "basic", "title": "Related Topics" } [/block] - <a href="https://docs.api.ai/docs/webhook-for-online-store-support-agent" target="_blank">Webhook Example for Online Store Support Agent</a>