In this blog post I will add an API to my bot, so that it can be called over HTTP using REST/JSON.

Create a Generic Bot

Navigate to your bot list at https://my.intwixt.com/#/bots.  Click on the menu item, CREATE BOT, and then chose Create Generic Bot.

Intwixt Bot List | Create Generic Bot

Intwixt Bot List | Create Generic Bot

The Create Generic Bot Dialog will now load.  Enter a title and description (optional), and then click CREATE.

Create Generic Bot Dialog

Create Generic Bot Dialog

The Intwixt Bot Designer will load, allowing you to add triggers and activities to your bot, so it can react to and interact with the outside world.

Add an HTTP Receiver

Add an HTTP Receiver trigger to your bot.  This will allow you to contact it as a RESTful API Endpoint. Begin by clicking the plus sign (+) in the upper left to create a trigger. Choose HTTP Receiver as its type (Option 1).

Intwixt Bot Designer | Create Trigger

Intwixt Bot Designer | Create Trigger

Define the API Signature

Your HTTP Receiver needs to define a model for its input and output, so callers know its signature.  This is done using data models. For this example, I'll use a simple model with only three fields: first, last, and email. Initially, I'll use the same model for both the input and the output in order to create a simple "echo" type API. Refer to the following video.

Add a Response Activity

Your API Bot is currently configured to respond with a message that includes three fields: first, last, and email.  In this step I'll add an activity to return these fields.  Begin by dragging the plus sign (+) in the upper left to append a new activity to your HTTP Trigger. Choose RETURN as the activity type (Option  1). 

Intwixt Bot Designer | Choose Return Activity Type

Intwixt Bot Designer | Choose Return Activity Type

With the activity type now set as Return, the designer will validate the activity and note any missing configuration.  In this case the first, last, and email fields must still be mapped.

Refer to the following video to see how to add the upstream mappings in order to echo the API input as its output.

Define Your Bot's API

By default, Intwixt assigns a title and path for your API. However, you should consider customizing it, so that its signature, method, and path reflect API best practices. The following video shows how to configure the most common settings including the API method, path, title, description, and tag. In a later section, I'll detail how to further refine the API to include sample data.

Activate your Bot

Your bot and its corresponding API are now ready to be activated. Expand the Designer menu on the lower left and choose Activate.

Intwixt Bot Designer | Activate Your Bot

Intwixt Bot Designer | Activate Your Bot

Test Your Bot's API

Once your Bot is active, you can use the Intwixt API Explorer to test it using REST/JSON. Refer to the following video detailing this process. Please note that if you pause your Bot, its API will likewise be paused, resulting in a 404 response message when you call the API. The access token used in this example is auto-generated by Intwixt when you open the API Explorer.  It allows you to call your API securely, so make sure to keep this token private if you want to protect your API endpoints.

Refine your Bot's API

Quality API docs don't just happen.  You need to take the time to author, refine, update and version them as necessary.  The following video shows how to improve your Bot's API, so that it better documents the input and output signature. This video also introduces how to add transformers to your mapped data to extend the capability of the Intwixt Data Mapper.

Conclusion

Adding a RESTful API to your Bot allows you to control, query and monitor your Bot over HTTP.

 

Comment