API Request

Last updated: May 15, 2026

API Request

The API Request tool allows your Fonio agent to query external APIs and webhooks during live calls, enabling real-time access to data from your own systems (e.g., order status, customer information, inventory levels).

Overview

API Requests are executed during active conversations when the agent needs to retrieve external data. The agent can use information gathered during the call (like order numbers or customer IDs) to make dynamic requests to your endpoints.

Supported Request Methods

The API Request tool supports standard HTTP methods including:

  • GET

  • POST

  • And other common HTTP methods

Request and Response Formats

Request Configuration

You can configure the following elements for your API requests:

  • Method: Choose the HTTP method (GET, POST, etc.)

  • URL: Your external endpoint URL

  • Headers: Set headers like Authorization and content-type: application/json

  • Parameters:

    • For GET requests: Parameters are sent in the query string

    • For POST requests: Parameters are sent in the request body

    • Fixed/Default Parameters: Static values like API keys or fixed IDs

    • Dynamic Parameters: Values filled by the agent during the conversation (e.g., order numbers, customer IDs)

Response Format

Your endpoint should return JSON with content-type: application/json.

The response can contain:

  • Structured data: Individual fields (recommended) – allows the agent to flexibly formulate responses

  • Pre-formatted text: Complete sentences or paragraphs

Structured JSON data is preferred as it gives the agent flexibility in how to present the information naturally in conversation.

Timeout

The default timeout for API requests is 5 seconds.

Setup Instructions

Basic Configuration

  1. In your assistant, navigate to Tools and add a new API Request tool

  2. Select the HTTP method (e.g., GET or POST)

  3. Enter your endpoint URL

  4. Configure headers (e.g., Authorization, content-type: application/json)

  5. Set up parameters:

    • Add fixed parameters for static values like API keys

    • Add dynamic parameters that the agent will fill from conversation data

  6. (Optional) Set an execution message that the agent will say while waiting for the response (e.g., "One moment, I'm checking the order status...")

  7. Test using "Audio testen" and check the logs to verify which parameters were sent and what data was returned

Using Dynamic Parameters

Dynamic parameters allow the agent to use information gathered during the conversation in API requests. You can view example dynamic parameters in the tool configuration interface.

Using Context Variables

If you have data available at call start (e.g., from an Inbound Webhook), you can reference context variables in your API requests using the syntax {{context.variableName}}. For example, {{context.customerId}} to pass a customer ID.

Triggering API Calls

To have the agent automatically trigger an API call when certain information is recognized:

  1. Add instructions in your assistant's prompt describing when to use the API tool

  2. Example: "When someone wants to check their order status, ask for the order number and start the API Call XY"

  3. For best results, have the agent actively ask for and confirm the required information (e.g., order number) before making the request

Example Use Case: Order Status Lookup

Setup

  1. Optional: Configure an Inbound Webhook to retrieve customer data at call start

  2. Create an API Request tool named "order_status":

    • Set your middleware endpoint URL

    • Add dynamic parameter: orderNumber (filled from conversation)

    • Add optional context parameter: customerId using {{context.customerId}}

    • Configure response fields: orderStatus, shippingStatus, carrier, trackingNumber, invoiceNumber, shippedAt

  3. Add instructions to your assistant prompt about when to use this tool (e.g., after confirming the order number)

Best Practices

  • Have the agent ask for and repeat/validate the order number before sending the request

  • Keep responses concise and clear

  • Provide helpful fallback responses when data is missing

  • Your external system only needs to provide a stable HTTP endpoint with JSON responses

Variable Extraction

Before using dynamic parameters from conversation data, you may need to configure variable extraction in the assistant's Technical Settings to ensure the agent properly captures values like order numbers.

Testing and Debugging

Use the "Audio testen" feature and check the logs to:

  • Verify which parameters were sent in the request

  • See what data was returned