Fulfillment

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

Webhook Requirements

Use the tabs below to explore the requirements your chosen web service should follow:

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 should preferably use HTTPS.

Request

When an intent in which a webhook was enabled is triggered, API.AI sends data to the service in the form of POST request with a POST body in the format of 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 API.AI 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 API.AI.
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 API.AI. 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.

Webhook for Slot Filling

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

Webhook Example

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