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.

Source Distribution

apiaiwebhook-0.1.0.dev2.tar.gz (20.0 kB view hashes)

Uploaded source

Built Distribution

apiaiwebhook-0.1.0.dev2-py2.py3-none-any.whl (22.0 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page