Use API Power-up

API Power-up overview

The use API power-up lets your bot call any API to get or send information. It is super flexible allowing you to define the arguments the bot needs to collect before using the API. These arguments can then be used to adjust the URL or to make up a post body.

Of course, to use this power-up you are going to need a good understanding of API requests, JSON and the the OpenAI function calling API, but if you do it opens up endless possibilities.

The best way to see how the use API power-up works is to watch the video below:

Example use-cases

This power-up allows you to integrate your bot with any service that has an API meaning you can get your bot to do all sorts of cool things. Here's a few examples to get your cogs turning:

• Hotel booking bot - Allow your bot to call an availability endpoint to retrieve live hotel availability to be used as part of a booking journey. We demoed this here: https://twitter.com/pixelhopio/status/1681016563938254850/video/1
• Surf forecast bot - Use a surf forecast API to create a bot that can let you know if its a good idea to go surfing today
• Server Monitor - Create a bot that can help you monitor your server infrastructure by hooking it into a metrics endpoint

API Power-up setup

After adding a new "Use API power-up" you will be presented with its settings page. In addition to the normal power-up settings (name & description etc) you will see a number of other sections that will allow you to configure the API request that will be made when the bot users this power-up.

Setting a name and description

Before you get into configuring the API request, take some time to add a name and description. The description should concisely explain the purpose of this power-up so the bot knows when to use it.

For example, in the screenshot below we are setting up the power-up to retrieve holiday property availability.

API arguments

The API power-up arguments section allows you to define the arguments your bot will collect and use when using the power-up.

For example you might add a "location" argument if you are interacting with a weather API, or an "email" argument if you are using the API power-up to subscribe users to a newsletter.

After defining arguments, they can be then used to build up a request body to post to your chosen API endpoint, used to modify the endpoint URL, or placed in request headers.

Depending on the how you define and describe the arguments, they might be provided by the user speaking with the bot, or the bot may try to fill them in itself.

For those of you familiar with OpenAI's function calling API, the power-up arguments are essentially the parameters that are passed when the function is defined to the model. See here for examples: How to call functions with chat models

To create the arguments you need to JSON schema object that is passed to OpenAI. Below is an example where we define the arguments required to interact with a holiday cottage availability search API.

You can see the 3 properties we have defined, their type, and their description. You can also see that we have added each of them to the "required" array so the bot knows that all the parameters are required each time it uses this power-up.

API request settings

The API request settings section is where you configure the endpoint URL you would like your bot to use, and the request type, GET, POST. PUT, PATCH, DELETE etc.

Sometimes you may need to adjust your URL based on the arguments you defined earlier. For example its common for API to use query parameters to adjust your request by passing information.

You can use the arguments you defined earlier in your endpoint URL to make it dynamic. If you defined an "arrivalDate" argument earlier you can use it in your URL like so:

https://example-api.com?date=<arrivalDate>

<arrivalDate> will be replaced by the bot with an actually date when the power-up is used.

API request headers

The API request headers allows you to configure the request headers that are used when calling your API. These headers are not made public so can include authentication headers if required.

The headers are defined as simple key value pairs in JSON.

API request body

If you have chosen a request type that supports a body (POST, PUT or PATCH) you will see the request body section. Here you can define the JSON body that will be sent as part of your API request. The body can include arguments that were defined earlier by using the argument name surrounded by < >. These will then be replaced by the actual values when the power-up is used.

Below is an example demonstrating the post body for an availability search API:

API response prompt

The API response prompt can be optionally used to pass the API response back through an LLM for the purpose of transforming it before returning the response to your bot. For example you could add a prompt that says "Extract the 10 most recent posts from this RSS feed and format them as markdown" , or "Convert the available properties into CSV format"

API Power-up tips

Debug arguments and responses

You can debug the arguments your bot is using to call your power-up by clicking the "View details" link next to where the power-up is called:

Clicking view details on the "Finish: Power-up" message will allow you to see the response from the API. You will also see any errors received from the API request here:

Do not use APIs with huge responses

The API response needs to fit in your model context window size. Some APIs return massive amounts of JSON and this will not work, or will be very inefficient for your bot to work with.

Its useful to only return the minimum amount of information required by your bot.