Configure API calls in your generative bot with Actions

Important

This feature is only available for bots that only contain generative content sourced from a knowledge base.

You can expand your bot's functionality by configuring Actions. Each Action consists of an API call that you can configure behind the scenes. Then, your bot will automatically determine when to use it and how to handle the response.

Limitations

Currently, you can only configure GET requests in Actions.
You can have a maximum of five active, chatter-facing Actions per bot. You can have additional draft Actions saved in your bot, but those won't affect your bot's responses.

Create an Action

On the Ada dashboard, go to Content > Actions.
If the API call you're configuring requires authentication, you can add an authentication token that Ada stores securely. Then, you can reference that token in one or more Actions, without the contents of the token being visible in the UI.
1. Click Manage tokens. The Tokens page opens.
2. Click New token. The Create Token window opens.
3. Under Name, enter a name for the token, and under Value, enter the token. Click Save. After you save the token, if you open it again, a censored version of the token will display for security reasons.
4. Click Actions to go back to the list of Actions. To reference the token in an Action, you can type @ and start typing the name of the token to insert it.
Click New Action. The New Action page opens.
Under Describe this Action, enter a Name and Description for the Action.
The Name and Description provide important context to your bot about when it should make the API call. Imagine you're explaining to a human agent when they should perform the API call and the information you want to provide to your customers - your name and description should cover this information.
Under List inputs, you can tell the bot to ask chatters for information it needs to make the API call. If your API call doesn't require any additional information from the chatter, you can skip this step.
Note
If you add inputs to your Action, you must also include them in your API call, or your bot won't save your Action.
1. Under Name, enter an identifier for the information you need to put into the API call.
  Make sure you format the name so it can go into a URL (e.g,. use underscores instead of spaces). The name should be descriptive so your bot knows what kind of information to collect from the chatter (e.g., email or order_id).
2. Under Type, select an information type, so your bot knows the format it should use in the API call.
You can click Add to add additional inputs as needed.
Under Make API call, enter the structure of the API call, using any tokens or inputs you created, or pieces of information the browser collected as a metavariable. For more information on how it does this, see setMetaFields at Ada's Developer Documentation.
1. On the Endpoint tab, under URL, enter the URL of the endpoint. You can type @ to see a list of available tokens, inputs, or metavariables that you can select as a placeholder to include in the URL.
2. If required, you can add headers to your call. To add headers, click the Headers tab, click Add headers, then add values in the Parameter and Value fields.
  You can click Add to continue adding additional headers as required.
3. Under This API uses, select either JSON or XML as the format of the API output.
Under Pick outputs, you can specify portions of the API response that your bot should save to include in its responses.
1. Under Name, enter a name for the output. Names help give your bot more context for how to use that output in its responses to chatters, and if applicable, in other Actions.
2. Under Path, enter a path to capture the desired portion of the API response.
  The Path field uses JMESPath, which is a syntax that allows you to target part of an API response. For instructions and examples, see Use JMESPath to save a portion of a JSON API response.
You can click Add to add additional outputs as needed.
At the top of the page, you can click Save changes to save your Action as a draft, or click Publish to test it and make it available to customers.
Click Test bot to ensure that your bot triggers your Action and includes information from the API response as expected.
Make sure you test different ways of phrasing questions, and if you included different outputs, different ways of asking for that information. If you find that your bot isn't responding properly, use an API client like Postman to verify that your call is formatted correctly, or consider editing the description of your Action or output names so your bot can understand them more clearly.
Tip
Because your bot sends the relevant portion of the API response through an LLM, the wording in your bot's responses varies between tests. While testing, focus on the information your bot sends back, rather than the exact wording the LLM generates.

Use JMESPath to save a portion of a JSON API response

You can use JMESPath to save portions of the API response for your bot to use with chatters. Even if the API response you're using is in XML format, your bot converts it to JSON so you can write all of your paths the same way.

As an example, let's use the Star Wars API, which returns information about the Star Wars movies. If you use the /films endpoint, you get a long list of films and attributes that looks something like this heavily truncated version:

{
  ...
  "results": [
    {
      "title": "A New Hope",
      "episode_id": 4,
      "opening_crawl": "It is a period of civil war...",
      "director": "George Lucas",
      "producer": "Gary Kurtz, Rick McCallum",
      "release_date": "1977-05-25",
      ...
    },
    {
      "title": "The Empire Strikes Back",
      "episode_id": 5,
      "opening_crawl": "It is a dark time for the Rebellion...",
      "director": "Irvin Kershner",
      "producer": "Gary Kurtz, Rick McCallum",
      "release_date": "1980-05-17",
      ...
    },
    ...
  ]
}

You can target particular attributes or arrays in the response, depending on how the response is structured and what you're looking for. We recommend using the JMESPath online evaluator with your API response to verify that your path is successfully targeting the attributes you need.

You can read the full documentation at the JMESPath website to learn about the full list of available operators, but to get started quickly, here are some important techniques you're likely to use:

In general, write a statement that goes from the broadest level of the API response down to the specific attributes that you're trying to target. Some responses only have one level, or maybe all you want is a top-level attribute, which means you don't have to worry about nesting. If that's the case, your path can just be the name of the attribute you want to target.
If your API response contains nested attributes, here are several ways to target them:
- After the parent attribute, you can denote which items in the array you want to target:
  - Use empty brackets [] to return all child items in a single list.
  - Put a number in the brackets, like [0], to return a specific child item. Again, remember that JMESPath starts counting at 0, not 1.
  - You can filter results based on criteria you put in the brackets.
- Use . before the name of a child attribute. You can target several levels of nested attributes if required.
If the name of an attribute contains a hyphen, you have to put it in double quotation marks "" so JMESPath can recognize it.

Here are a few simple examples of how to target specific parts of the Star Wars API response:

Intent	JMESPath	Result
Save everything in the `results` array	`results`	[ { "title": "A New Hope", "episode_id": 4, "opening_crawl": "It is a period of civil war...", "director": "George Lucas", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1977-05-25", ... }, { "title": "The Empire Strikes Back", "episode_id": 5, "opening_crawl": "It is a dark time for the Rebellion...", "director": "Irvin Kershner", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1980-05-17", ... }, ... ]
Save all movie titles in the response	`results[].title`	[ "A New Hope", "The Empire Strikes Back", "Return of the Jedi", "The Phantom Menace", "Attack of the Clones", "Revenge of the Sith" ]
Save all info associated with the first movie in the response	`results[0]`	{ "title": "A New Hope", "episode_id": 4, "opening_crawl": "It is a period of civil war...", "director": "George Lucas", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1977-05-25", ... }
Save the name of the director of the first movie in the response	`results[0].director`	"George Lucas"
Save a list of characters that were in the first movie in the response	`results[0].characters`	[ [ "https://swapi.dev/api/people/1/", "https://swapi.dev/api/people/2/", "https://swapi.dev/api/people/3/", "https://swapi.dev/api/people/4/", "https://swapi.dev/api/people/5/", ... ] ]
Save a list of movie titles that were released before January 1, 1990	results[?release_date<`1990-01-01`].title	[ "A New Hope", "The Empire Strikes Back", "Return of the Jedi" ]

Edit or delete an Action

At any time, you can go back to an Action to edit or delete it.

On the Ada dashboard, go to Content > Actions.
Click the Action you want to modify, then make the required changes.
- If the Action is a draft and you want to save changes to the draft without making the Action available to chatters, click Save changes.
- If the Action is a draft and you want to make it active, click Publish. As soon as you publish it, it becomes available to chatters.
- If the Action is active and you want to remove it from being active without deleting it, click Convert to draft. As soon as it becomes a draft, chatters stop being able to use it.
- To delete the Action, click the More options button and click Delete Action. In the confirmation message that appears, click Delete again.

Have any questions? Contact your Ada team—or email us at help@ada.support.

In this section: