Configure API calls with Actions

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.

You can have a maximum of five active, customer-facing Actions per bot. You can have additional draft Actions saved in your bot, but those won't affect your bot's responses.

note

This feature may not be included with your organization's subscription package. For more information, see Ada's Pricing page, or contact your Ada team.

Create an Action

On the Ada dashboard, go to Training > Actions.
If the API call you're configuring requires authentication, you can add an authentication token that Ada stores securely. For more information, see Authenticate your AI Agent's API calls using tokens.

Then, you can reference that token in one or more Actions, without the contents of the token being visible in the UI. 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 Identify this Action, enter a Name and Description for the Action.

The Name and Description provide important context to your AI Agent 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.

If required, you can restrict Actions to certain users, based on information your AI Agent collects about your users and saves in variables.

note

You can only use variables your AI Agent can collect through your browser, or that you collect in a block and allow to be available outside of the structured content the block is in. You can't use variables your AI Agent collects using other Actions.

To make the Action available to all users, select Everyone.

To restrict the Action to certain users, select Based on the following rules. A section expands where you can enter the logic your AI Agent will use to decide whether to serve the Action.

Beside Where, in the Choose a variable list, select a variable.

In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target.

Understand comparison operators

Comparison operators are logic statements that tell your AI Agent to match customer information that’s captured in the variable you’re using. The available operators vary based on the variable type you’re using:

Operator	Variable types	Description
Begins With	All text variables (including phone and email)	Match information in the variable that begins with certain text (partial match).
Ends With	All text variables (including phone and email)	Match information in the variable that ends with certain text (partial match).
Contains	All text variables (including phone and email) List variables	Match information in the variable that contains certain text in any position (partial match).
Is	All text variables (including phone and email) Number variables	Match information in the variable that equals specific text exactly (exact match).
Is Not	All text variables (including phone and email) Number variables	Match information in the variable that does not equal specific text exactly (exact match).
Is Not Set	All text variables (including phone and email) Number variables List variables	Match if there is no information contained in the variable.
Is Set	All text variables (including phone and email) Number variables List variables	Match if there is any information contained in the variable.
Greater Than	Number variables	Match if the information in the variable is greater than a specific value.
Less Than	Number variables List variables	Match if the information in the variable is less than a specific value.
Is True	Yes/No variables	Match if the information in a variable is Yes (or True).
Is False	Yes/No variables	Match if the information in a variable is No (or False).
Does Not Contain	List variables	Match if none of the selected items contains this value.
Is Equal To	List variables	Match if the customer selected a particular number of options in a List Option block.
Is Greater Than	List variables	Match if the customer selected more than a particular number of options in a List Option block.
Is Less Than	List variables	Match if the customer selected fewer than a particular number of options in a List Option block.

In the Value field, enter or select a value for the variable that you want to use to target users.
If required, add additional conditions.
- By default, if you click the Add icon , new conditions will be added with "or" statements, meaning customers will see the Action if they fulfil any of your criteria.
- You can click And to add additional conditions that must all be satisfied for your AI Agent to serve the Action.

Under Get input from chat, you can tell the AI Agent to ask customers for information it needs to make the API call. If your API call doesn't require any additional information from the customer, you can skip this step.

note
If you add inputs to your Action, you must also include them in your API call, or your AI Agent won't save your Action.
1. Under Input, 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 AI Agent knows what kind of information to collect from the customer (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 Connect to API, 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. Under Method, choose the HTTP method for your call (GET, POST, PATCH, PUT, or DELETE).
3. 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.
4. If you're making a POST, PATCH, or PUT request, on the Body tab, enter the payload for your request.
5. Under This API uses, select either JSON or XML as the format of the input, if your call has a payload, and the output from the API.
Under Test API Response, you can test the API response to test whether it's properly configured. From there, you can target portions of that response for your AI Agent to use in its responses to customers.
- If your call doesn't have any custom inputs, click Test to make a test call.
- If you created custom inputs, click Set test values. The Set test values window opens. For each input, enter a value to temporarily use for your test API call. Then, click Save and test to make a test call using those values.
If your call was successful, a response appears. You can hover over a portion of the response to highlight it, then click Add output to automatically populate the path to that portion of the response as an output for the next step.

Under Use API outputs in chat (Optional), you can specify portions of the API response that your bot should save to include in its responses. If you don't specify any outputs, your AI Agent will still make the API call, but it won't use any information from the response when generating replies to customers.

Under Output, enter a name for the output. Names help give your bot more context for how to use that output in its responses to customers, and if applicable, in other Actions.

Under Path, either enter a path to capture the desired portion of the API response, or use a pre-populated path from your response.

The Path field uses JMESPath, which is a syntax that allows you to target part of an API response. For instructions and examples you can use if you need to write your own, click to open this expander:

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 customers. 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" ]`

You can click Add, or click additional portions of the test response, 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.

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 Training > 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 customers, 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 customers.
- 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, customers 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 [email protected].

Configure API calls with Actions

Create an Action​

Edit or delete an Action​

Create an Action

Edit or delete an Action