> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom HTTP Tools

> Enable your AI agents to call external APIs during conversations

Custom tools allow your AI agents to access external information by connecting to your APIs.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant AI Agent
    participant Your API

    Customer->>AI Agent: "What's my account balance?"
    AI Agent->>Customer: "Let me look that up. What's your account number?"
    Customer->>AI Agent: "ACC-12345"
    AI Agent->>Your API: GET /balance?account=ACC-12345
    Your API-->>AI Agent: {"balance": 1250.50, "currency": "USD"}
    AI Agent->>Customer: "Your current balance is $1,250.50"
```

## Setup

<Steps>
  <Step title="Navigate to Agent Settings">
    Go to your agent settings
  </Step>

  <Step title="Add Custom Tool">
    In the Tools section click **+ Add** to create a new custom tool
  </Step>

  <Step title="Configure Basic Settings">
    Fill in the configuration:

    | Field                | Description                                              |
    | -------------------- | -------------------------------------------------------- |
    | **Name**             | Identifier for your tool (e.g., `check_account_balance`) |
    | **Description**      | What the tool does and when to use it.                   |
    | **HTTP Method**      | GET, POST, PUT, PATCH, or DELETE                         |
    | **URL**              | Your API endpoint (must use HTTPS)                       |
    | **Response Timeout** | 1-10 seconds                                             |
  </Step>

  <Step title="Add Parameters">
    Configure headers, query parameters, and request body using the value types
    below
  </Step>

  <Step title="Update System Prompt (Optional)">
    Add business rules and conversation flow for using the tool in your agent's system prompt
  </Step>
</Steps>

## Value Types

Use these value types for headers, query parameters, and request body:

| Type                | Description                    | Use Case                     |
| ------------------- | ------------------------------ | ---------------------------- |
| **Constant**        | Static values                  | Fixed config                 |
| **System Variable** | Contact/call data              | Customer email, phone number |
| **LLM Parameter**   | AI-extracted from conversation | Account numbers, product IDs |
| **Secret**          | Encrypted sensitive data       | Auth tokens, passwords       |

### System Variable

To add contact and call data to your request you can use two available types:

**Standard Fields:** Built-in contact and call information

* `contact.firstName`, `contact.lastName`, `contact.phoneNumber`, `contact.externalId`
* `call.id`

Use the dropdown in the UI to browse all available variables.

**Contact Details:** Custom fields you define per contact (accessed via `contact.contactDetails.*`)

* Example: `contact.contactDetails.customerId`, `contact.contactDetails.accountTier`

### LLM Parameter

The AI extracts these values from the conversation by asking questions or inferring from context. When you configure an LLM Parameter, you provide:

* **Name**: The parameter name in the API request
* **Description**: Instructions for the AI on what to extract and the expected format
* **Data Type**: String, Number, or Boolean

The AI uses the description to understand when and how to collect this information from the customer.

**Example:** A parameter named `account_number` with description "Customer's account number (format: ACC-12345)" tells the AI to ask for and extract an account number in that format.