HTTP API Tool

The HTTP API tool lets your agent call any external REST API during a conversation. When the LLM decides to use the tool, the platform sends an HTTP request with the parameters the LLM extracted from the conversation and returns the response to the LLM so it can continue talking.

How It Works

Caller: "Can you book me an appointment for Tuesday at 3pm?"
    |
    v
LLM recognizes "Book Appointment" tool matches this intent
    |
    v
LLM extracts: date = "Tuesday", time = "3:00 PM"
    |
    v
Platform sends: POST https://api.example.com/appointments
                Body: {"date": "Tuesday", "time": "3:00 PM"}
    |
    v
API responds: {"status": "confirmed", "id": "APT-1234"}
    |
    v
LLM says: "Your appointment is confirmed for Tuesday at 3pm.
           Your confirmation number is APT-1234."

The LLM never sees your tool's internal configuration (URL, headers, credentials). It only sees the tool name, description, and parameter definitions.

Configuration Reference

The HTTP API tool editor is organized into three tabs: Settings, Authentication, and Parameters.

Settings Tab

Custom Message (Hold Message)

The custom messages are spoken (or played as audio) before the tool executes. Use them for hold messages like "Let me check that for you, one moment."

Authentication Tab

Authentication is handled through Credentials -- reusable, encrypted authentication configurations stored separately from the tool. Select an existing credential or create a new one directly from the tool editor.

Credential Types

When creating a credential, you choose one of these types:

Parameters Tab

Parameters define what information the LLM needs to extract from the conversation to call the tool. Each parameter becomes a field in the function schema the LLM sees.

How Parameters Are Sent

The HTTP method determines where parameters are placed in the request:

Writing Effective Parameter Descriptions

The LLM extracts parameter values from the conversation based on each parameter's name and description. Be specific:

Custom Headers

Static key-value pairs added to every request. Use for content types, API versions, or other fixed headers. These are separate from authentication headers.

Example: Booking API Tool

Here is a complete example of an HTTP API tool that books appointments.

Tool Configuration

Settings:

• Name: Book Appointment
• Description: Use this tool when the caller wants to book, reschedule, or cancel an appointment. Extract the date, time, and service type from the conversation.
• Method: POST
• URL: https://api.example.com/v1/appointments
• Timeout: 5000 ms
• Custom Message: Let me book that for you, one moment.

Authentication:

• Credential: A Bearer Token credential with your API token.

Parameters:

What the Platform Sends

curl -X POST "https://api.example.com/v1/appointments" \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "John Smith",
    "date": "2026-05-25",
    "time": "15:00",
    "service": "consultation"
  }'

What the LLM Receives Back

{
  "status": "confirmed",
  "appointment_id": "APT-2026-1234",
  "date": "2026-05-25",
  "time": "15:00",
  "service": "consultation",
  "provider": "Dr. Sarah Chen"
}

The LLM then responds to the caller:

"Your consultation appointment is confirmed for May 25th at 3 PM with Dr. Sarah Chen. Your confirmation number is APT-2026-1234."

Example: Weather Lookup Tool (GET)

Settings:

• Name: Get Weather
• Description: Use this tool when the caller asks about the weather in a specific location. Returns current temperature and conditions.
• Method: GET
• URL: https://api.weatherapi.com/v1/current.json
• Timeout: 5000 ms

Authentication:

• Credential: An API Key credential with header name key and your WeatherAPI key.

Parameters:

Equivalent curl (GET parameters become query string):

curl -X GET "https://api.weatherapi.com/v1/current.json?q=London" \
  -H "key: your-api-key-here"

Response Handling

The full HTTP response body is returned to the LLM as the tool result. The LLM interprets the response and incorporates relevant information into its next spoken message. There is no need to configure response parsing -- the LLM handles JSON, XML, and plain text responses natively.

Error Handling

Tool Definition Schema

The full JSON schema for an HTTP API tool definition, as stored in the definition field:

{
  "schema_version": 1,
  "type": "function",
  "config": {
    "method": "POST",
    "url": "https://api.example.com/endpoint",
    "timeout_ms": 5000,
    "headers": {
      "X-Custom-Header": "value"
    },
    "credential_uuid": "cred-uuid-here-or-null",
    "parameters": [
      {
        "name": "param_name",
        "type": "string",
        "description": "What this parameter represents",
        "required": true
      }
    ],
    "customMessages": ["Let me check that for you.", "One moment please."],
    "customMessageType": "text",
    "customMessageRecordingId": null
  }
}

Best Practices

1. Use specific tool descriptions -- the LLM decides which tool to call based on the description. Vague descriptions lead to incorrect tool selection.
2. Set realistic timeouts -- default is 5 seconds. Increase for slow APIs, but always pair with a custom hold message.
3. Mark optional parameters as non-required -- this lets the LLM call the tool even when the caller doesn't mention every field.
4. Use credentials for authentication -- never put API keys in custom headers or the URL. Credentials are encrypted and never exposed to the LLM.
5. Test your endpoint independently -- before configuring the tool, verify the API works with a curl command. The tool sends exactly the same request.