API.AI Webhook is a fulfillment microframework for API.AI based on Flask for getting started quickly with API.AI webhooks.

Install the package with

pip install apiaiwebhook

A minimal api.ai Webhook application looks like this:

from apiaiwebhook import APIAIWebhook
app = APIAIWebhook(__name__)

@app.fulfillment("hello-world")
def hello_world():
    return app.make_response_apiai(speech="Hello World!")

if __name__ == '__main__':
    app.run()

To run the application, just execute the python file:

python hello_world.py

To test the application, you can use either the in-built api.ai test client

app.testing = True
res = app.test_client_apiai().webhook(action="hello-world"})
assert res.status_code == 200
assert ""Hello, World!" in res.data

Or you can use curl

curl -X POST -H "Content-Type: application/json" -d '{"result": {"action": "hello-world"}}' http://127.0.0.1:5000/webhook    

The parameters are extracted from results/parameters. This dictionary is passed to the fulfillment function via ** operator (unpacked):

{
    "results": {
        "action": "hello-world",
        "parameters": {
            "parameter": "example value"
            }
    }
}

The fulfillment function declaration should look like this:

@app.fulfillment("hello-world")
def hello_world(parameter = None, **kwargs):
    return app.make_response_apiai(speech="Hello, %s!" % parameter)

The default value is required when the parameter can be empty. Kwargs is useful when additional parameters are expected in the future.

The webhook dispatcher responses:

• HTTP 400 when api_key_value is defined but it the authentication header is not provided.
• HTTP 401 when api_key_value is defined but it is invalid.
• HTTP 404 when fulfillment function is not defined for the provided action.

Otherwise it returns a valid application/json content-type HTTP response. The response can be create using the helper function of make_response_apiai()

Example:

    @app.fulfillment("hello-world")
    def my_fulfillment_none():
        return app.make_response_apiai(speech="Hello, World!"
                                       display_text="Hello, World! I am please to meet you!")

The response will be like:

    {
        "speech": "Hello, World!",
        "displayText": "Hello, World! I am please to meet you!",
        "data": None,
        "contextOut": [],
        "source": <name of Flask application>,
        "followupEvent": None
    }

The APIAIWebhook class defines the initialization parameters of api_key_header (default is api-key) and api_key_value (default is None) parameters.

In order to secure your webhook, define a shared secret:

from apiaiwebhook import APIAIWebhook
app = APIAIWebhook(__name__, api_key_value="secret") 

Then configure the authentication header in your API.AI agent.

The API.AI Webhook Client extends the Flask Client in order to post valid webhook messages.

app.testing = True
app.debug = True
r = app.test_client_apiai().webhook(action="hello-world",
                                    parameters={"param": "value"})

The APIAIWebhook class is derived from Flask. Visit the official website to extend the functionality of API.AI Webhook

Before running or deploying this application, install the framework using pip:

pip install -e .

To test the framework, execute the unit tests via:

python unit_tests.py