Custom events

Custom events are events you create to signify some communication that can't be captured easily through text or voice. Custom events can indicate that a user has clicked a button, provided authorization, or that a certain amount of time has passed. These events can be triggered through Dialogflow fulfillment or the detect intent API. These events can be handled in your Dialogflow agent or in fulfillment.

Define 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 API.

In an intent, locate the Events section and enter the event name(s) in the text field:

To add events via the API, add a string to the events field list in the intent object, as seen in the HTTP request below:

PATCH Authorization: Bearer <AccessToken>
https://dialogflow.googleapis.com/v2/projects/<ProjectID>/agent/intents/<IntentID>
{
  "events": [
    "event-name-1",
    "event-name-2"
    ...
  ]
  ...
}

See the API reference and authentication guide for more information on how to make this request.

Invoke an event via the detect intent API

To trigger a specific intent by event name, send a detect intent API request containing an event parameter value that corresponds to the event name. 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 detect intent request to the parameters defined in the Action and parameters section of the intent, and also reference these parameter values in the Response section of the triggered intent.

  • To reference an event parameter in the parameter table or a response, use the following format: #event-name.parameter-name.
POST Authorization: Bearer <AccessToken>
https://dialogflow.googleapis.com/v2/projects/<ProjectID>/agent/sessions/<SessionID>:detectIntent
{
        "queryInput": {
                "event": {
                        "name": "event-name",
                        "parameters": {
                                "parameter-name-1": "parameter-value-1",
                                "parameter-name-2": "parameter-value-2",
                                ...
                        },
                        "languageCode": "en-US"
                }
        }
}

See the API reference and authentication guide for more information on how to make this request.

Invoke event from webhook

You can invoke events via fulfillment by sending the event name with the followupEvent parameter in the response from your web service. You can use the followup event input object to pass parameter values from the data object to the parameters manually defined in the Action and parameters section of the intent, or reference these parameter values in the Response section of the triggered intent.

  • To reference an event parameter in the parameter table or a response, use the following format: #event-name.parameter-name.

To trigger a followup event from fulfillment, send a response to Dialogflow's webhook request that takes the following form:

{
  "followupEventInput": {
    "name": "event-name",
    "parameters": {
      "parameter-name-1": "parameter-value-1",
      "parameter-name-2": "parameter-value-2"
    },
    "languageCode": "en-US"
  }
}

When a followup event is triggered from the webhook, the event specified in the webhook response is triggered. Triggering the event through a webhook sends the request back through Dialogflow for matching without responding to the user. The response to the user is sent as if the user triggered the event that was triggered in the webhook. After the second intent is matched by the event, Dialogflow will do any necessary work (like webhook calls or additional prompts for required parameters) and send a response back as if the second intent was the originally matched intent.

  1. A user sends a request to Dialogflow.
  2. "Intent 1" is matched by Dialogflow.
  3. A webhook request is sent to your fulfillment server, which indicates that intent 1 was matched.
  4. Your fulfillment server responds to the webhook request with a followup event response.
  5. Dialogflow re-matches intent 2 based on the followup event sent in the webhook response.
  6. Dialogflow sends a response to the user based solely on intent 2 being matched. Dialogflow may send another webhook call indicating intent 2 was matched, or send a prompt for unfulfilled required parameters (if configured) for intent 2.