We’ve changed our name! API.AI is now Dialogflow. Learn more here.

Events

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 /query request containing an "event" parameter.

Event Name

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 one-click integrations.

Event Name Platform
WELCOME Google Assistant, Facebook Messenger, Telegram, Kik. See more in Default Welcome Intent.
GOOGLE_ASSISTANT_WELCOME Google Assistant (Actions on Google)
FACEBOOK_WELCOME Facebook Messenger
TELEGRAM_WELCOME Telegram
KIK_WELCOME Kik
SLACK_WELCOME Slack
SKYPE_WELCOME Skype

Defining Event Names in Intents

You can define an event name in an intent in the developer console or via the API with the help of the /intents endpoint.

While in an intent, click Events below the User Says section and enter the event name(s).

To add events via the API, use the “events” field in the intent object in the following format:

"events": [
    {
        "name": "<event_name>"
    }
]

Invoking an Event via Query Request

To trigger a specific intent by event name, send a /query 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:

curl -H "Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN" "https://api.dialogflow.com/v1/query?v=20150910&e=event_name&timezone=Europe/Paris&lang=en&sessionId=1234567890"

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, Dialogflow creates a context with the same name as the event name and context "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:

  2. Send a POST /query request with the "event" parameter containing the user name:

    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.dialogflow.com/api/query?v=20150910"
            

    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"
    }
            

Default Welcome Intent

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.

When the end-user triggers a welcome intent from a supported messaging platform, the relevant event is sent to Dialogflow. 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, Dialogflow checks for intents containing the FACEBOOK_WELCOME event. If no such intent is found, the Default Welcome Intent is triggered.

Invoking Event from Webhook

You can invoke events via fulfillment by sending event name with the "followupEvent" parameter in the response from your web service.

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 JSON response 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 Dialogflow 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.