Skip to main content

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

Project description

# API.AI Webhook ![Travis CI build status image for master branch](

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

## Users' Guide

### Quick Start

Install the package with

pip install apiaiwebhook

A minimal Webhook application looks like this:

from apiaiwebhook import APIAIWebhook
app = APIAIWebhook(__name__)

def hello_world():
return app.make_response_apiai(speech="Hello World!")

if __name__ == '__main__':

To run the application, just execute the python file:


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

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

Or you can use curl

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

### Parameters

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:

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.

### Response
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()`


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

### Securing
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.

### Testing

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"})

### Flask
The `APIAIWebhook` class is derived from `Flask`. Visit the official [website]( to extend the functionality of API.AI Webhook

## Development

Before running or deploying this application, install the framework using

pip install -e .

To test the framework, execute the unit tests via:


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
apiaiwebhook-0.1.0.dev2-py2.py3-none-any.whl (22.0 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Jun 19, 2017
apiaiwebhook-0.1.0.dev2.tar.gz (20.0 kB) Copy SHA256 hash SHA256 Source None Jun 19, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page