> This page is for version Generative (default).
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Action control

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](https://www.ada.cx/pricing) page, or contact your Ada team.

## Create an Action\[#create-an-action]

1. On the Ada dashboard, go to **Training** > **Actions**.

2. 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](/generative/docs/automation/actions/token-configuration).

   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.

3. Click **New Action**. The New Action page opens.

4. 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.

5. Under **Set usage**, the **AI Agent only uses this Action within Processes** check box is selected by default. This means that the Action is restricted to only being used when a [Process](/generative/docs/automation/processes/process-management) refers to it.

   Clear the check box if you want your AI Agent to be able to run the action independently, rather than in a larger step-by-step Process.

6. If required, you can restrict articles 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 Actions.

   * To make the article available to all users, select **Everyone**.

   * To restrict the article 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 article.

     1. Under **Where**, in the **Choose a variable** list, select a variable.
     2. 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 icon](/_fern-files/_img/e8b9c807586a4238654793da51b49ec15e7045c0691d461567178070e57a1840.webp) **Begins With**           | - All text variables (including phone and email)                                     | Match information in the variable that begins with certain text (partial match).                 |
     | ![Ends With icon](/_fern-files/_img/9bc404d3db5ea684a901bf8426485894bb62abb8369e498b98dc4e4f3807a5ec.webp) **Ends With**               | - All text variables (including phone and email)                                     | Match information in the variable that ends with certain text (partial match).                   |
     | ![Contains icon](/_fern-files/_img/a4f0225811b1ecde2f125de907c2ad1b084268805cd89a00f465649ddbf8eaa2.webp) **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 icon](/_fern-files/_img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is**                             | - All text variables (including phone and email) - Number variables                  | Match information in the variable that equals specific text exactly (exact match).               |
     | ![Is Not icon](/_fern-files/_img/d94952ab65e9f266413c582390a1d702ebb32c7a2023709ee96741b6df1b17e4.webp) **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 icon](/_fern-files/_img/283cad3d89c7d92f279d722592cd958630a40527266a47d316ab3b3b2051b71f.webp) **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 icon](/_fern-files/_img/8c1019797a0482018682d52622c9e2fe56ddc5aef8925dc3e3db678c121c6869.webp) **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 icon](/_fern-files/_img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Greater Than**         | - Number variables                                                                   | Match if the information in the variable is greater than a specific value.                       |
     | ![Less Than icon](/_fern-files/_img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Less Than**               | - Number variables - List variables                                                  | Match if the information in the variable is less than a specific value.                          |
     | ![Is True icon](/_fern-files/_img/fcf3fe21099df957ee22609d5a5c211601d3e402fcc8402c12115f4680a692b0.webp) **Is True**                   | - Yes/No variables                                                                   | Match if the information in a variable is Yes (or True).                                         |
     | ![Is False icon](/_fern-files/_img/2b5c661e7e4445f1ea8f7736ee5b58b14f72283faf2dbd4f01220a26d621b238.webp) **Is False**                 | - Yes/No variables                                                                   | Match if the information in a variable is No (or False).                                         |
     | ![Does Not Contain icon](/_fern-files/_img/2a459cf7a992abeb5cbdf8438f9f1be356bb5fcf915f55f7f1c2cdc3173b101d.webp) **Does Not Contain** | - List variables                                                                     | Match if none of the selected items contains this value.                                         |
     | ![Is Equal To icon](/_fern-files/_img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is Equal To**           | - List variables                                                                     | Match if the customer selected a particular number of options in a List Option block.            |
     | ![Is Greater Than icon](/_fern-files/_img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **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 icon](/_fern-files/_img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Is Less Than**         | - List variables                                                                     | Match if the customer selected fewer than a particular number of options in a List Option block. |
     6. In the **Value** field, enter or select a value for the variable that you want to use to target users.
     7. If required, add additional conditions.
     * To add a new **top-level** condition, click **Add** ![](/_fern-files/_img/eaf3e27905dfafde4c1138201d5674737788133775fed7625fcd3f098c6628f3.webp).

       If you're adding your first additional top-level condition, in the dropdown that appears, choose **And** or **Or** as the operator for all of your top-level conditions.

     * To create or add to a **group** of conditions, click the **Add to group** icon ![](/_fern-files/_img/881a5902ee010bd99b16914b2ac663810ad93cade88c2fddc273b4c3bc508b28.webp) beside a condition you want to include in the group.

       If you're creating a group, in the dropdown that appears, choose **And** or **Or** as the operator for all of the conditions in that group.

7. 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.
   2. 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`).

   You can click **Add** to add additional inputs as needed.

8. 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](https://developers.ada.cx/reference/embed2-reference#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.

9. 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.

10. 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.

    1. 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.
    2. 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](https://swapi.dev/documentation), 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:
    ```json
    {
      ...
      "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](https://jmespath.org/) with your API response to verify that
    your path is successfully targeting the attributes you need.

    You can read the [full documentation](https://jmespath.org/tutorial.html) 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:
    <table>
      <thead>
        <tr>
          <th>
            Intent
          </th>

          <th>
            JMESPath
          </th>

          <th>
            Result
          </th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            Save everything in the `results` array
          </td>

          <td>
            `results`
          </td>

          <td>
            ```json
            [
              {
                "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",
                ...
              },
              ...
            ]
            ```
          </td>
        </tr>

        <tr>
          <td>
            Save all movie titles in the response
          </td>

          <td>
            `results[].title`
          </td>

          <td>
            ```json
            [
              "A New Hope",
              "The Empire Strikes Back",
              "Return of the Jedi",
              "The Phantom Menace",
              "Attack of the Clones",
              "Revenge of the Sith"
            ]
            ```
          </td>
        </tr>

        <tr>
          <td>
            Save all info associated with the first movie in the
            response
          </td>

          <td>
            `results[0]`
          </td>

          <td>
            ```json
            {
              "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",
              ...
            }
            ```
          </td>
        </tr>

        <tr>
          <td>
            Save the name of the director of the first movie in the
            response
          </td>

          <td>
            `results[0].director`
          </td>

          <td>
            ```
            "George Lucas"
            ```
          </td>
        </tr>

        <tr>
          <td>
            Save a list of characters that were in the first movie in the
            response
          </td>

          <td>
            `results[0].characters`
          </td>

          <td>
            ```json
            [
              [
                "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/",
                ...
              ]
            ]
            ```
          </td>
        </tr>

        <tr>
          <td>
            Save a list of movie titles that were released before January 1,
            1990
          </td>

          <td>
            ``results[?release_date<`1990-01-01`].title``
          </td>

          <td>
            ```json
            [
              "A New Hope",
              "The Empire Strikes Back",
              "Return of the Jedi"
            ]
            ```
          </td>
        </tr>
      </tbody>
    </table>

    You can click **Add**, or click additional portions of the test response, to add additional outputs as needed.

11. 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.

12. 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\[#UUID-5a6fd489-8115-32c5-1055-a1bb8b2f00c3_section-idm4605534416368033931003632602]

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

1. On the Ada dashboard, go to **Training** > **Actions**.

2. 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 ![](/_fern-files/_img/92f471415d4d83cfacae59466c84e0bf868d9e4c6ac35dea1211ad64140bcd87.webp) and
     click **Delete Action**. In the confirmation message that appears,
     click **Delete** again.

---

Have any questions? Contact your Ada team, or email us at [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).