Fulfillment

Webhook

Setting up a webhook allows you to pass information from a matched intent into a web service and get a result from it.

Requirements

Authentication

Authentication can be done in 2 ways:

  • Basic authentication with login and password.
  • Authentication with additional authentication headers.

If the integrated service doesn’t require any authentication, leave the authentication fields blank.

The service must use HTTPS and the URL must be publicly accessible.

Request

When an intent in which a webhook was enabled is triggered, Dialogflow sends data to the service in the form of POST request with a POST body in the format of a response to a query.

If a request is sent from one of the messaging platforms, the originalRequest field is added to the response to a query.

This format is chosen in order to simplify the response parsing on the service side with the help of Dialogflow SDKs.

Sample Request to the Service
POST https://my-service.com/action
    
Headers:
//user defined headers
Content-type: application/json
    
POST body:
 
{
    "lang": "en", 
    "status": {
        "errorType": "success", 
        "code": 200
    }, 
    "timestamp": "2017-02-09T16:06:01.908Z", 
    "sessionId": "1486656220806", 
    "result": {
        "parameters": {
            "city": "Rome", 
            "name": "Ana"
        }, 
        "contexts": [], 
        "resolvedQuery": "my name is Ana and I live in Rome", 
        "source": "agent", 
        "score": 1.0, 
        "speech": "", 
        "fulfillment": {
            "messages": [
                {
                    "speech": "Hi Ana! Nice to meet you!", 
                    "type": 0
                }
            ], 
            "speech": "Hi Ana! Nice to meet you!"
        }, 
        "actionIncomplete": false, 
        "action": "greetings", 
        "metadata": {
            "intentId": "9f41ef7c-82fa-42a7-9a30-49a93e2c14d0", 
            "webhookForSlotFillingUsed": "false", 
            "intentName": "greetings", 
            "webhookUsed": "true"
        }
    }, 
    "id": "ab30d214-f4bb-4cdd-ae36-31caac7a6693", 
    "originalRequest": {
        "source": "google", 
        "data": {
            "inputs": [
                {
                    "raw_inputs": [
                        {
                            "query": "my name is Ana and I live in Rome", 
                            "input_type": 2
                        }
                    ], 
                    "intent": "assistant.intent.action.TEXT", 
                    "arguments": [
                        {
                            "text_value": "my name is Ana and I live in Rome", 
                            "raw_text": "my name is Ana and I live in Rome", 
                            "name": "text"
                        }
                    ]
                }
            ], 
            "user": {
                "user_id": "PuQndWs1OMjUYwVJMYqwJv0/KT8satJHAUQGiGPDQ7A="
            }, 
            "conversation": {
                "conversation_id": "1486656220806", 
                "type": 2, 
                "conversation_token": "[]"
            }
        }
    }
}

Response

The response from the service should have the following fields:

Name Type Description
speech String Response to the request.
displayText String Text displayed on the user device screen.
data Object Additional data required for performing the action on the client side. The data is sent to the client in the original form and is not processed by Dialogflow.
contextOut Array of context objects

Array of context objects set after intent completion. Example:

`"contextOut": [{"name":"weather", "lifespan":2, "parameters":{"city":"Rome"}}]`
source String Data source.
followupEvent Object

Event name and optional parameters sent from the web service to Dialogflow. Example:

{"followupEvent":
    {
        "name":"event_name",
        "data":{
            "parameter_name":"parameter_value"
        }
    }
}
Read more.
Sample Response from the Service
Headers:
Content-type: application/json

Body:
{
    "speech": "Barack Hussein Obama II was the 44th and current President of the United States.",
    "displayText": "Barack Hussein Obama II was the 44th and current President of the United States, and the first African American to hold the office. Born in Honolulu, Hawaii, Obama is a graduate of Columbia University   and Harvard Law School, where ",
    "data": {...},
    "contextOut": [...],
    "source": "DuckDuckGo"
}

Errors

The service should be able to handle the following errors:

  • 400 Bad Request – The request was invalid or cannot be served.
  • 401 Unauthorized – The request requires user authentication.
  • 403 Forbidden – The server understood the request but refuses to take any further action or the access is not allowed.
  • 404 Not found – There is no resource behind the URI.
  • 500 Server fault – Internal Server Error.
  • 503 Service Unavailable – Internal Server Error.

In case of these or other errors (timeout limit exceeded, service is not available), the “status” in the response sent to the client will contain the following:

"status": {
    "code": 206,
    "errorType": "webhook call failed with %error Code% error"
  }

where error Code is the error ID received from the service.

Limits

  • Timeout for service response – 5 seconds.
  • Data received in the response from the service – up to 64K.

Slot Filling

If you want to send requests for required parameters from Dialogflow to your web service, check the option Use webhook for slot filling in the Fulfillment section of the intent.

Example

Check out the second part of our getting started guide, Basic Fulfillment and Conversation Setup, for steps on setting up fulfillment.

Cloud Functions for Firebase

For simple webhook testing and implementation, you can use the Cloud Functions for Firebase area of the Fulfillment page. In most cases the free "Spark" tier of Firebase is all you'll need. Tier limitations and pricing information for the other tiers can be found on the Firebase pricing page.

To enable:

  1. Click on Fulfillment in the left menu.
  2. Click the switch for Inline Editor.

Some basic, functional code provided to help you get started.

To deploy your fulfillment, click the Deploy button under the code editor.

After clicking Deploy, Dialogflow will save your Cloud Function for Firebase and begin the deployment process. When deployment is complete, you'll see a timestamp next to the Deploy button, signifying the last time the function was deployed.

The link under the code editor can be used to visit the function's logs in the Firebase console. This is used to debug issues and get information on your function.

"Graduating" your code

Once you're ready to move your code out of the Fulfillment page, you can use the Download button to get a .ZIP file of your code in it's current state. Using the Firebase CLI, you can unzip your code locally and deploy more complex fulfillment code.

Limitations

Here is a list of things to be aware of when using the Cloud Functions for Firebase option:

  • If you modify your function outside of code editor, you can no longer use the Dialogflow editor to modify your Cloud Function for Firebase. Your function will continue to provide fulfillment for your agent, but if you need to make changes, you will need to do so in the Firebase console.

  • The function must be named "dialogflowFirebaseFulfillment". If you change the name of your function it will not deploy via Dialogflow. If you want to change the name of your function you can download the code, change the function name, and deploy through Firebase's CLI.

  • Code modified in the dialogflow editor cannot be saved or downloaded without being deployed.

  • Dialogflow's editor only supports two files: index.js and package.json (modifying package.json will install any dependencies you specify upon deployment)

  • Network calls originating from your Cloud Function for Firebase to destinations outside Google's network require billing to be enabled for the underlying Google Cloud or Firebase project.