Recently, API.AI revamped their documentation quite significantly. In the process, there has been a clear move towards favoring the Google Cloud over Heroku. This is understandable, considering Google acquired API.AI recently. 😉
In the process though, the API.AI developer community is now required to go through a much more challenging initiation to webhooks, and I had this view confirmed by a few private online conversations too. Earlier, the webhook sample had a one-click deploy to the Heroku cloud, and you could get the example up and running in practically no time.
So, I have decided to retrace the old steps, combine it with the online resources that I could find, and tried to somewhat simplify the process for folks trying to get started with webhooks. This is possible because Heroku is much more "prototype" friendly when compared to the Google Cloud, which makes it particularly well suited for hobbyist developers who are just dabbling in API.AI to evaluate its capabilities.
So here is the step by step process for deploying an API.AI webhook on Heroku.
Sign up for Heroku
As you know, you can sign up for free. Once you sign up, log in to Heroku.
The logged in view looks something like this.
Click to deploy from GitHub while logged in
Go to this URL:
Click on the big "Deploy to Heroku" button.
Complete deployment from inside Heroku
Click on the Deploy button. Once you click it, Heroku will create a new project for you by running some scripts and will complete the deployment and show you a success message like below.
Copy the webhook URL
Click on the View button. You should see an error message. Don't worry about the error message, it is expected.
Copy the URL in the browser bar.
Prepare your API.AI agent
If you haven't done so already, create a new agent inside API.AI.
Provide Fulfillment info
The fulfillment tab is where you paste your webhook URL.
When pasting, make sure to append the word webhook, and check that the URL looks like below:
Remember to Save your new information using the Save button at the top.
Create the API.AI Intent
Create an intent called weather. Declare the userSays phrases as shown.
Important: Make sure the action is set to yahooWeatherForecast as shown below.
Be sure to use webhook fulfillment in the intent
Scroll down to the bottom of the "weather" intent you created, and fill out the Default Response and more importantly, check the Use Webhook for fulfillment.
Also note the Default response: turns out, the Heroku app can go to sleep after 30 minutes of inactivity. In general, your webhook could fail to respond for many different reasons. So make sure you have some kind of "Service unavailable" message when you use webhooks.
Test in your console
When you type the following (as an example):
weather in Boston
you should get the following back. (If you get service unavailable, just type it in one more time).
So with that, you are now ready to start using webhooks in API.AI.
Here is a demo video which also covers mostly what I have shown here.
Migrating webhook code to API v2
I have created a mini-course which explains how you can migrate your Python webhook code from v1 to v2 API.