How do I configure an API in Virtual Agent?

Last updated: July 31, 2026

Overview

API actions permit a Virtual Agent to call an external system during a live interaction, for example, verifying a reservation, fetching order status, or updating a record.

Integrate your desired APIs once under Tools & Settings, test it in isolation, and then use them as an action in your Skill or Node in your Workflows, so the agent can call it at the right moment.

Integrate the following types of API actions:

Action type

What it does

API method type

Read

Retrieves data without changing database

(e.g., verify a booking, search for options)

• GET

Note: Some API actions might perform reads via the POST method.

Write

Modify/update data in the external system

(e.g., update a reservation, log a transaction, redeem miles)

• POST
• PUT
• PATCH

This article covers configuring the API action. To use a configured API action in a skill or flow, see How do I add API actions to a Virtual Agent flow?

Key concepts

Term

What it means

Example

Params

Key-value pairs appended to the endpoint URL after the ? delimiter to filter, sort, or paginate response data.

Adding ?type=shoes&color=blue to a store URL to see only blue shoes.

Input variables

Runtime values injected into the URI path, headers, or body at execution time to pass dynamic context.

Inserting a customer's specific account number {{12345}} into the lookup path.

Headers

Metadata fields passed in the request header block for authentication, content negotiation, and protocol instructions.

Sending Authorization: Bearer <token> to prove the user has permission to access the data.

Body

The data payload transmitted in the HTTP message body containing the resource state to be created or modified.

Sending a text package containing a new user's name, email, and password to sign them up.

Before you begin

Make sure you have:

  • URLs of API endpoints for each operation you want the agent to perform (for example, for data stored in Airtable: the base ID and table ID(s) in the URL).

  • Credentials to setup the API authorization.

  • A clear list of which input parameters will be used in the API action.

Configure an API Action

  1. From the left navigation bar, click Virtual Agent > open your virtual agent > click the Tools & Settings tab.

  2. In the left panel, select APIs.

  3. Click + Integrate New API.

    image.png

  4. Enter the following details:

  • API Name — A clear, specific name for your API action. The agent uses this name to call the action.

    Sample API names: Verify_Reservation, Search_Flight_Options, Update_Reservation.

  • Description (optional) — Briefly describe what this endpoint is intended to perform, for future reference.

    image.png

  1. Click Proceed. The API configuration screen opens.

  2. Set the Method and HTTPS URL:

  • Enter your API endpoint URL in the HTTPS URL field.

  • Select an appropriate method (GET, POST, PUT, PATCH, and DELETE) from the dropdown. Ensure you select the correct method to avoid errors.

  • For record-specific writes, include the record reference directly in the URL path (for example, .../tableId/{{recordId}}).

    image.png

The configuration screen organizes the rest of setup into the following tabs. Configure each as needed:

Configure Input Variables

The Input Variables tab automatically populates any variables you’ve entered in the URL, Header or Body tabs. These values are captured at runtime during the API call against the configured variables.

To directly configure a variable in the API query URL use double curly brackets: {{variable}}.

You can also mark these variables as Mandatory or Optional depending on the query requirements.

image.png

Configure Query Parameters (Params)

Info: Any parameter added to the query string URL is automatically reflected in the Params section.

  1. From the Params tab, click + Key value pair and enter a Key, a Value, and an optional Description.

  2. To pass a value in Params at runtime, use double curly braces {{param}}, for example {{reservation_id}}.

    image.png

Configure Authorization

  1. Open the Authorization tab.

  2. Configure the supported authorization method as per your endpoint. Supported methods are:

    1. Basic Auth

    2. Bearer Token

    3. OAuth 2.0

    4. Cookie Session

image.png

Configure Header

  1. Open the Headers tab.

  2. Click + Key value pair and add any headers the endpoint needs — for example, Content-Type → application/json.

    image.png

Configure Body

Note: The Body tab is visible only for PUT, PATCH, and POST methods.

  1. Open the Body tab and select the format:

    • Form-data

    • x-www-form-urlencoded

    • Raw (Text)

    • Raw (JSON)

  2. The body must be a fixed JSON object with tokens for the values. The agent supplies only the values, never the structure.

  3. Once you're done, click Save from the top-right corner to Save the configuration.

    image.png

Advanced Settings

Important: Advanced Settings applies to Voice Virtual Agents only.

Defines the action's interruptibility for the voice agent. When the action type is set to Write or state change, the action cannot be interrupted during execution, and the agent will only respond after the action completes.

  1. Expand the Advanced Settings menu at the bottom of the API configuration menu.

  2. Select an action type: Read only or Write or state change.

    image.png

Testing Configured API

  1. Click Test to run the configured API

    Note: If Test button is disabled, click Save first. If Save is also disabled, the configuration is likely incomplete — verify all tabs, then try again.

  2. Enter values for any variables, if applicable.

  3. Click Run.

  4. Review the response. If you get an error, adjust the configuration and re-test until you get a successful response.

    image.png

Best Practices

  • Name each API action precisely — the name is part of how the agent decides when to call it.

  • Build the read actions first, confirm verification and search work, then add writes.

  • Use fixed JSON bodies with tokens. Never let the agent compose the body structure.

  • Apply authentication to every action, not just reads.

  • Mark writes as a write/state change before testing on voice. This ensures that user interruption is avoided during execution.

  • Test every API action standalone and confirm a successful response (200) before using it in a skill.

  • To use APIs reliably with a voice agent, configure a tool preamble to reduce perceived latency for the end user.

  • If an API action should not be interrupted during execution, mark the tool as non-interruptible.

  • Always test an API action before using it. Avoid using the production database during API action testing.