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
FACEBOOK_WELCOME Facebook Messenger
FACEBOOK_LOCATION Facebook Messenger - See more below
GOOGLE_ASSISTANT_WELCOME Google Assistant (Actions on Google)
KIK_WELCOME Kik
SLACK_WELCOME Slack
SKYPE_WELCOME Skype
TELEGRAM_WELCOME Telegram

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 above the Training Phrases 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" \
    "https://api.dialogflow.com/api/query?v=20150910" \
    --data "{
    'event':{'name': 'custom_event', 'data': {'name': 'Sam'}},
    'timezone':'America/New_York',
    'lang':'en',
    'sessionId':'1321321'}"
    

    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.

FACEBOOK_LOCATION

The FACEBOOK_LOCATION event allows you to get a location from Facebook Messenger.

  1. Create an intent to request the location, using a custom payload:

    {
      "facebook": {
        "text": "give me your location please",
        "quick_replies": [
          {
            "content_type": "location"
          }
        ]
      }
    }
    
  2. Create another intent to process the location and set the event to FACEBOOK_LOCATION.

  3. In the webhook, you'll receive the latitude and longitude from the originalRequest field:

V2 API

{
  "originalDetectIntentRequest": {
    "source": "facebook",
    "payload": {
      "postback": {
        "data": {
          "lat": 14.556761479425,
          "long": 121.05444780425
        },
        "payload": "FACEBOOK_LOCATION"
      },
      "sender": {
        "id": "1588949991188331"
      }
    }
  }
}

V1 API

{
  "source": "facebook",
  "data": {
    "postback": {
      "data": {
        "lat": 37.428434,
        "long": -122.0723816
      },
      "payload": "FACEBOOK_LOCATION"
    },
  }
}