{"__v":0,"_id":"5845a4a99f6fbb1b004307f5","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307b9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:25:25.645Z","from_sync":false,"order":1,"slug":"key-concepts","title":"Key Concepts"},"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-12-04T22:40:32.024Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"* [Overview](#overview)\n* [Event Name](#event-name)\n* [Defining Event Names in Intents](#defining-event-names-in-intents)\n* [Invoking an Event via Query Request](#invoking-an-event-via-query-request)\n * [GET /query Request](#section-get-query-request)\n * [POST /query Request](#section-post-query-request)\n * [Sending Parameters in a Query Request](#section-sending-parameters-in-a-query-request)\n* [Default Welcome Intent](#default-welcome-intent)\n* [Invoking Event from Webhook](#invoking-event-from-webhook)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\n**Events** is a feature that allows you to invoke intents by an **event name** instead of a user query.\n\nFirst, you define event names in intents. Then, you can trigger these intents by sending a <a href=\"https://docs.api.ai/docs/query\" target=\"_blank\">/query</a> request containing an `\"event\"` parameter.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Event Name\"\n}\n[/block]\nEvent name is a string up to 50 characters long. It may contain Latin letters (a-z A-Z), digits (0-9), underscore (_), and hyphen (-). Event names are case insensitive.\n\nSome strings are reserved. For example, event names that invoke events in the supported messaging platforms integrated into your agent with the help of <a href=\"https://docs.api.ai/docs/integrations\" target=\"_blank\">one-click integrations</a>.\n\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr>\\n  \\t<th>Event Name</th>\\n  \\t<th>Platform</th>\\n  </tr>\\n  <tr>\\n  \\t<td>WELCOME</td>\\n  \\t<td>Google Assistant, Facebook Messenger, Telegram, Kik, Slack, Skype.\\nSee more in <a href=\\\"https://docs.api.ai/docs/concept-events#default-welcome-intent\\\">Default Welcome Intent</a>.</td>\\n  </tr>\\n  <tr>\\n  \\t<td>GOOGLE_ASSISTANT_WELCOME</td>\\n  \\t<td>Google Assistant (Actions on Google)</td>\\n  </tr>\\n  <tr>\\n  <tr>\\n  \\t<td>FACEBOOK_WELCOME</td>\\n  \\t<td>Facebook Messenger</td>\\n  </tr>\\n  <tr>\\n  \\t<td>TELEGRAM_WELCOME</td>\\n  \\t<td>Telegram</td>\\n  </tr>\\n  <tr>\\n  \\t<td>KIK_WELCOME</td>\\n  \\t<td>Kik</td>\\n  </tr>\\n  <tr>\\n  \\t<td>SLACK_WELCOME</td>\\n  \\t<td>Slack</td>\\n  </tr>\\n  <tr>\\n  \\t<td>SKYPE_WELCOME</td>\\n  \\t<td>Skype</td>\\n  </tr>\\n</table>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Defining Event Names in Intents\"\n}\n[/block]\nYou can define an event name in an intent in the developer console or via the API with the help of the <a href=\"https://docs.api.ai/docs/intents\" target=\"_blank\">/intents</a> endpoint.\n\nIn the developer console, click ‘Events’ below the ‘User says’ section and enter the event name(s).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/28248bd-Events_enter-event-name.png\",\n        \"Events_enter-event-name.png\",\n        2024,\n        744,\n        \"#268fc5\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nTo add events via the API, use the “events” field in the <a href=\"https://docs.api.ai/docs/intents#intent-object\" target=\"_blank\">intent object</a> in the following format:\n```\n  \"events\": [\n    {\n      \"name\": \"<event_name>\"\n    }\n  ]\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Invoking an Event via Query Request\"\n}\n[/block]\nTo trigger a specific intent by event name, send a  <a href=\"https://docs.api.ai/docs/query\" target=\"_blank\">/query</a> request containing an “event” parameter value that corresponds to the event name.\n\nA query request should contain either the `\"query\"` or `\"event\"` parameter. \n\n## GET /query Request\n\nIf you use the GET method to invoke an event, you can send the event name in the following format: `e=<event_name>`. \n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\\\" \\\"https://api.api.ai/v1/query?v=20150910&e=event_name&timezone=Europe/Paris&lang=en&sessionId=1234567890\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n## POST /query Request\n\nIf you use the POST method to invoke an event, the `“event”` parameter value is an object of the following format:\n\n```\n   \"event\":{  \n      \"name\":\"<event_name>\",\n      \"data\":{\n          “<parameter_name>”:”<parameter_value>”  \n      }\n   }\n ```\n\n## Sending Parameters in a Query Request\n\nWhen you send a query request with an `\"event\"` parameter, API.AI creates a context with the same name as the event name and `\"lifespan\": 0`. This lifespan value means that the context is active only during the current request. \n\nYou can use this context to pass parameter values from the “data” object to the parameters manually defined in the ‘Action’ section of the intent or reference these parameter values in the ‘Response’ section of the triggered intent.  To do so, use the following format: `#event_name.parameter_name_from_data`.\n\nThe following example sends a user name to your custom welcome intent invoked by the event and references this name in the text response.\n\n1. Define the event name, parameter value, and text response in the following way:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6b761e9-Events_Custom_welcome_intent_UI.png\",\n        \"Events_Custom_welcome_intent_UI.png\",\n        2026,\n        1264,\n        \"#f8f8f8\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n2. Send a POST /query request with the `\"event\"` parameter containing the user name:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -H \\\"Content-Type: application/json; charset=utf-8\\\" -H \\\"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\\\" --data \\\"{'event':{ 'name': 'custom_event', 'data': {'name': 'Sam'}}, 'timezone':'America/New_York', 'lang':'en', 'sessionId':'1321321'}\\\" \\\"https://api.api.ai/api/query?v=20150910\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe JSON response to this query will look like this:\n\n```\n{\n  \"id\": \"a3a27316-572a-443f-bdb9-ca65dd2325d6\",\n  \"timestamp\": \"2016-12-01T19:46:07.379Z\",\n  \"result\": {\n    \"source\": \"agent\",\n    \"resolvedQuery\": \"custom_event\",\n    \"action\": \"welcome\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"user_name\": \"Sam\"\n    },\n    \"contexts\": [\n      {\n        \"name\": \"custom_event\",\n        \"parameters\": {\n          \"user_name\": \"Sam\",\n          \"name\": \"Sam\",\n          \"user_name.original\": \"\"\n        },\n        \"lifespan\": 0\n      }\n    ],\n    \"metadata\": {\n      \"intentId\": \"ade506c7-851b-4f62-ba85-2f33023d079a\",\n      \"webhookUsed\": \"false\",\n      \"webhookForSlotFillingUsed\": \"false\",\n      \"intentName\": \"Custom welcome intent\"\n    },\n    \"fulfillment\": {\n      \"speech\": \"Welcome, Sam!\",\n      \"messages\": [\n        {\n          \"type\": 0,\n          \"speech\": \"Welcome, Sam!\"\n        }\n      ]\n    },\n    \"score\": 1.0\n  },\n  \"status\": {\n    \"code\": 200,\n    \"errorType\": \"success\"\n  },\n  \"sessionId\": \"1321321\"\n}\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Default Welcome Intent\"\n}\n[/block]\nWhen you create a new agent, a Default Welcome Intent is automatically added. Such intents have a pre-defined WELCOME event and text responses. \n\nThe WELCOME event is a generic event for supported one-click integrations. It’s a short way to set the following events: GOOGLE_ASSISTANT_WELCOME, FACEBOOK_WELCOME, TELEGRAM_WELCOME, KIK_WELCOME, SLACK_WELCOME, SKYPE_WELCOME.\n\nWhen the end-user triggers a welcome intent from a supported messaging platform, the relevant event is sent to API.AI. If there is no other intent with a defined event specific to a particular messaging platform, the Default Welcome Intent is triggered. \n\nFor example, if a user clicks the ‘Get started’ button in Facebook Messenger, a query containing `{\"event\": {\"name\": \"FACEBOOK_WELCOME\", \"data\": {}}` is sent to the agent. First, API.AI checks for intents containing the FACEBOOK_WELCOME event. If no such intent is found, the Default Welcome Intent is triggered.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Invoking Event from Webhook\"\n}\n[/block]\nYou can invoke events via <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">webhook</a> by sending event name with the `\"followupEvent\"` parameter in the <a href=\"https://docs.api.ai/docs/webhook#section-format-of-response-from-the-service\" target=\"_blank\">response from your web service</a>.\n\nThe `\"followupEvent\"` parameter value is an object of the following format:\n\n```\n{\n   \"followupEvent\": {\n      \"name\": \"<event_name>\",\n      \"data\": {\n         \"<parameter_name>\": \"<parameter_value>\"\n      }\n   }\n}\n```\n\nWhen the `\"followupEvent\"` parameter is sent from the web service, the system ignores `\"speech\"`, `\"displayText\"`, and `\"data\"` fields.\n\nWhen an intent which sends a request to the web service to trigger the follow-up intent afterwards is triggered, the `\"metadata\"` field in the <a href=\"https://docs.api.ai/docs/query#response\" target=\"_blank\">JSON response</a> contains the `\"executionSequence\"` field. Its value is an array of objects corresponding to the intent sequence. The first object in the sequence contains information about the intent that is responsible for firing the sequence, i.e., sending the request from API.AI to the web service. The `\"webhookTriggeringEvent\"` value in the first object is an event name that triggers the follow-up intent from the web service.\n\nThe following example shows that the sequence started from the “Amount” intent in which webhook is enabled. That intent invoked the `\"my_custom_event\"` event from the web service. By this event, the “Event” intent (in which the event is defined) was triggered. \n\n```\n{\n    \"metadata\": {\n      \"intentId\": \"d213b0be-2699-43d5-a4e7-5952919906b9\",\n      \"executionSequence\": [\n        {\n          \"source\": \"agent\",\n          \"intentId\": \"816d4f13-b677-4ced-b5c4-ae5b810a55f0\",\n          \"action\": \"amount\",\n          \"intentName\": \"Amount\",\n          \"webhookUsed\": true,\n          \"webhookTriggeringEvent\": \"my_custom_event\"\n        },\n        {\n          \"source\": \"agent\",\n          \"intentId\": \"d213b0be-2699-43d5-a4e7-5952919906b9\",\n          \"action\": \"event\",\n          \"intentName\": \"Event\",\n          \"webhookUsed\": false\n        }\n      ],\n      \"webhookUsed\": \"false\",\n      \"webhookForSlotFillingUsed\": \"false\",\n      \"intentName\": \"Event\"\n    }\n}\n```\nIf you send parameters in the `\"followupEvent\"` object, you can reference parameter values in the 'Response' section in the following format: `#event_name.parameter_name`.\n\n**Limits:**\n\nMaximum number of sequential webhook calls per request – 3\nTotal webhook execution timeout – 10 seconds","excerpt":"","slug":"concept-events","type":"basic","title":"Events"}
* [Overview](#overview) * [Event Name](#event-name) * [Defining Event Names in Intents](#defining-event-names-in-intents) * [Invoking an Event via Query Request](#invoking-an-event-via-query-request) * [GET /query Request](#section-get-query-request) * [POST /query Request](#section-post-query-request) * [Sending Parameters in a Query Request](#section-sending-parameters-in-a-query-request) * [Default Welcome Intent](#default-welcome-intent) * [Invoking Event from Webhook](#invoking-event-from-webhook) [block:api-header] { "type": "basic", "title": "Overview" } [/block] **Events** is a feature that allows you to invoke intents by an **event name** instead of a user query. First, you define event names in intents. Then, you can trigger these intents by sending a <a href="https://docs.api.ai/docs/query" target="_blank">/query</a> request containing an `"event"` parameter. [block:api-header] { "type": "basic", "title": "Event Name" } [/block] Event name is a string up to 50 characters long. It may contain Latin letters (a-z A-Z), digits (0-9), underscore (_), and hyphen (-). Event names are case insensitive. Some strings are reserved. For example, event names that invoke events in the supported messaging platforms integrated into your agent with the help of <a href="https://docs.api.ai/docs/integrations" target="_blank">one-click integrations</a>. [block:html] { "html": "<table>\n <tr>\n \t<th>Event Name</th>\n \t<th>Platform</th>\n </tr>\n <tr>\n \t<td>WELCOME</td>\n \t<td>Google Assistant, Facebook Messenger, Telegram, Kik, Slack, Skype.\nSee more in <a href=\"https://docs.api.ai/docs/concept-events#default-welcome-intent\">Default Welcome Intent</a>.</td>\n </tr>\n <tr>\n \t<td>GOOGLE_ASSISTANT_WELCOME</td>\n \t<td>Google Assistant (Actions on Google)</td>\n </tr>\n <tr>\n <tr>\n \t<td>FACEBOOK_WELCOME</td>\n \t<td>Facebook Messenger</td>\n </tr>\n <tr>\n \t<td>TELEGRAM_WELCOME</td>\n \t<td>Telegram</td>\n </tr>\n <tr>\n \t<td>KIK_WELCOME</td>\n \t<td>Kik</td>\n </tr>\n <tr>\n \t<td>SLACK_WELCOME</td>\n \t<td>Slack</td>\n </tr>\n <tr>\n \t<td>SKYPE_WELCOME</td>\n \t<td>Skype</td>\n </tr>\n</table>" } [/block] [block:api-header] { "type": "basic", "title": "Defining Event Names in Intents" } [/block] You can define an event name in an intent in the developer console or via the API with the help of the <a href="https://docs.api.ai/docs/intents" target="_blank">/intents</a> endpoint. In the developer console, click ‘Events’ below the ‘User says’ section and enter the event name(s). [block:image] { "images": [ { "image": [ "https://files.readme.io/28248bd-Events_enter-event-name.png", "Events_enter-event-name.png", 2024, 744, "#268fc5" ], "sizing": "full" } ] } [/block] To add events via the API, use the “events” field in the <a href="https://docs.api.ai/docs/intents#intent-object" target="_blank">intent object</a> in the following format: ``` "events": [ { "name": "<event_name>" } ] ``` [block:api-header] { "type": "basic", "title": "Invoking an Event via Query Request" } [/block] To trigger a specific intent by event name, send a <a href="https://docs.api.ai/docs/query" target="_blank">/query</a> request containing an “event” parameter value that corresponds to the event name. A query request should contain either the `"query"` or `"event"` parameter. ## GET /query Request If you use the GET method to invoke an event, you can send the event name in the following format: `e=<event_name>`. For example: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\" \"https://api.api.ai/v1/query?v=20150910&e=event_name&timezone=Europe/Paris&lang=en&sessionId=1234567890\"", "language": "curl" } ] } [/block] ## POST /query Request If you use the POST method to invoke an event, the `“event”` parameter value is an object of the following format: ``` "event":{ "name":"<event_name>", "data":{ “<parameter_name>”:”<parameter_value>” } } ``` ## Sending Parameters in a Query Request When you send a query request with an `"event"` parameter, API.AI creates a context with the same name as the event name and `"lifespan": 0`. This lifespan value means that the context is active only during the current request. You can use this context to pass parameter values from the “data” object to the parameters manually defined in the ‘Action’ section of the intent or reference these parameter values in the ‘Response’ section of the triggered intent. To do so, use the following format: `#event_name.parameter_name_from_data`. The following example sends a user name to your custom welcome intent invoked by the event and references this name in the text response. 1. Define the event name, parameter value, and text response in the following way: [block:image] { "images": [ { "image": [ "https://files.readme.io/6b761e9-Events_Custom_welcome_intent_UI.png", "Events_Custom_welcome_intent_UI.png", 2026, 1264, "#f8f8f8" ], "sizing": "full" } ] } [/block] 2. Send a POST /query request with the `"event"` parameter containing the user name: [block:code] { "codes": [ { "code": "curl -X POST -H \"Content-Type: application/json; charset=utf-8\" -H \"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\" --data \"{'event':{ 'name': 'custom_event', 'data': {'name': 'Sam'}}, 'timezone':'America/New_York', 'lang':'en', 'sessionId':'1321321'}\" \"https://api.api.ai/api/query?v=20150910\"", "language": "curl" } ] } [/block] The JSON response to this query will look like this: ``` { "id": "a3a27316-572a-443f-bdb9-ca65dd2325d6", "timestamp": "2016-12-01T19:46:07.379Z", "result": { "source": "agent", "resolvedQuery": "custom_event", "action": "welcome", "actionIncomplete": false, "parameters": { "user_name": "Sam" }, "contexts": [ { "name": "custom_event", "parameters": { "user_name": "Sam", "name": "Sam", "user_name.original": "" }, "lifespan": 0 } ], "metadata": { "intentId": "ade506c7-851b-4f62-ba85-2f33023d079a", "webhookUsed": "false", "webhookForSlotFillingUsed": "false", "intentName": "Custom welcome intent" }, "fulfillment": { "speech": "Welcome, Sam!", "messages": [ { "type": 0, "speech": "Welcome, Sam!" } ] }, "score": 1.0 }, "status": { "code": 200, "errorType": "success" }, "sessionId": "1321321" } ``` [block:api-header] { "type": "basic", "title": "Default Welcome Intent" } [/block] When you create a new agent, a Default Welcome Intent is automatically added. Such intents have a pre-defined WELCOME event and text responses. The WELCOME event is a generic event for supported one-click integrations. It’s a short way to set the following events: GOOGLE_ASSISTANT_WELCOME, FACEBOOK_WELCOME, TELEGRAM_WELCOME, KIK_WELCOME, SLACK_WELCOME, SKYPE_WELCOME. When the end-user triggers a welcome intent from a supported messaging platform, the relevant event is sent to API.AI. If there is no other intent with a defined event specific to a particular messaging platform, the Default Welcome Intent is triggered. For example, if a user clicks the ‘Get started’ button in Facebook Messenger, a query containing `{"event": {"name": "FACEBOOK_WELCOME", "data": {}}` is sent to the agent. First, API.AI checks for intents containing the FACEBOOK_WELCOME event. If no such intent is found, the Default Welcome Intent is triggered. [block:api-header] { "type": "basic", "title": "Invoking Event from Webhook" } [/block] You can invoke events via <a href="https://docs.api.ai/docs/webhook" target="_blank">webhook</a> by sending event name with the `"followupEvent"` parameter in the <a href="https://docs.api.ai/docs/webhook#section-format-of-response-from-the-service" target="_blank">response from your web service</a>. The `"followupEvent"` parameter value is an object of the following format: ``` { "followupEvent": { "name": "<event_name>", "data": { "<parameter_name>": "<parameter_value>" } } } ``` When the `"followupEvent"` parameter is sent from the web service, the system ignores `"speech"`, `"displayText"`, and `"data"` fields. When an intent which sends a request to the web service to trigger the follow-up intent afterwards is triggered, the `"metadata"` field in the <a href="https://docs.api.ai/docs/query#response" target="_blank">JSON response</a> contains the `"executionSequence"` field. Its value is an array of objects corresponding to the intent sequence. The first object in the sequence contains information about the intent that is responsible for firing the sequence, i.e., sending the request from API.AI to the web service. The `"webhookTriggeringEvent"` value in the first object is an event name that triggers the follow-up intent from the web service. The following example shows that the sequence started from the “Amount” intent in which webhook is enabled. That intent invoked the `"my_custom_event"` event from the web service. By this event, the “Event” intent (in which the event is defined) was triggered. ``` { "metadata": { "intentId": "d213b0be-2699-43d5-a4e7-5952919906b9", "executionSequence": [ { "source": "agent", "intentId": "816d4f13-b677-4ced-b5c4-ae5b810a55f0", "action": "amount", "intentName": "Amount", "webhookUsed": true, "webhookTriggeringEvent": "my_custom_event" }, { "source": "agent", "intentId": "d213b0be-2699-43d5-a4e7-5952919906b9", "action": "event", "intentName": "Event", "webhookUsed": false } ], "webhookUsed": "false", "webhookForSlotFillingUsed": "false", "intentName": "Event" } } ``` If you send parameters in the `"followupEvent"` object, you can reference parameter values in the 'Response' section in the following format: `#event_name.parameter_name`. **Limits:** Maximum number of sequential webhook calls per request – 3 Total webhook execution timeout – 10 seconds