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

# Custom Tools & APIs

> Enable your AI Voice Agent to call external REST APIs, n8n automations, CRM webhooks, or slot checkers in real time during live voice calls.

Your AI Voice Agent can dynamically trigger external REST APIs and webhooks (such as **n8n, Make.com, Zapier, custom CRMs, internal databases, or booking engines**) in the middle of live phone calls.

The agent extracts spoken parameters from the conversation (e.g., date, time, customer name, order number), makes the HTTP request in real time, and speaks the returned result back to the caller naturally.

***

## 1. How Dynamic Tool Calling Works

```mermaid theme={null}
sequenceDiagram
    autonumber
    Caller->>AI Voice Agent: "Can you check if there is an appointment slot tomorrow at 3 PM?"
    AI Voice Agent->>Custom API / Webhook: POST https://api.yourcompany.com/slots {"date": "2026-08-21", "time": "15:00"}
    Custom API / Webhook-->>AI Voice Agent: HTTP 200 {"available": true, "slot": "3:00 PM"}
    AI Voice Agent->>Caller: "Yes! 3:00 PM tomorrow is open. Would you like me to book it for you?"
```

***

## 2. Adding a Custom Tool to Your Agent

To configure a custom tool for your AI Agent:

1. Open your agent from the dashboard.
2. In the configuration panel, click the **Custom Tools** tab.
3. Click **Add Custom Tool** in the top right.
4. Fill in the tool configuration fields:

### Configuration Fields

| Field            | Description                                                                                | Example                                                            |
| :--------------- | :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
| **Tool Name**    | Unique identifier (letters, numbers, underscores only). Max 64 characters.                 | `check_slot_availability` or `trigger_n8n_lead`                    |
| **Description**  | Clear description of what the tool does. Gemini uses this to decide when to call the tool. | `Check available demo or meeting slots for a given date and time.` |
| **HTTP Method**  | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.                                                | `POST`                                                             |
| **Endpoint URL** | The full HTTPS URL of your API or webhook.                                                 | `https://api.yourcompany.com/slots`                                |
| **Timeout (ms)** | Maximum execution wait time before aborting (default: `5000ms`).                           | `5000`                                                             |

***

## 3. Configuring Custom Headers & Authentication

If your API requires an API key, Bearer token, or custom headers:

1. Under the **Headers** section, click **+ Add Header**.
2. Enter the key and value:

| Header Key      | Header Value                    | Use Case                    |
| :-------------- | :------------------------------ | :-------------------------- |
| `Authorization` | `Bearer your_secret_token_here` | Bearer Token Authentication |
| `X-API-Key`     | `live_sk_9f8e7d6c5b4a3210`      | Custom API Key Auth         |
| `Content-Type`  | `application/json`              | JSON Payload                |

<Note>
  Headers are securely stored and sent directly by your backend server on every request. They are never exposed to the caller.
</Note>

***

## 4. Configuring Tool Parameters

Parameters define the data that the AI will extract from the caller's spoken words or pass as fixed default values:

1. Under the **Parameters** section, click **+ Add Parameter**.
2. Configure each parameter:
   * **Name**: The JSON key (e.g. `date`, `time`, `order_id`, `customer_name`).
   * **Type**: `string`, `number`, `integer`, or `boolean`.
   * **Description**: Guidance for the AI (e.g. `Date in YYYY-MM-DD format (e.g. 2026-08-21)`).
   * **Required**: Check if the tool cannot execute without this parameter.

### Passing Hardcoded or Default Values

If you want the AI to always pass a fixed value (such as a company ID or fixed phone number) without asking the caller:

* In the **Description**, write: `Always pass "+919019068738"` or `Fixed user ID. Always pass "USR_12345"`.
* The AI will automatically include that exact value in the payload without asking the customer.

***

## 5. Testing Your Tool in the Dashboard

Before placing a live call, you can test your tool directly from the dashboard:

1. On the tool card, click the **Test** (▶️) button.
2. Enter sample test parameter values in the modal.
3. Click **Run Test**.
4. The modal will display the exact HTTP status (`HTTP 200 SUCCESS`, `401`, `500`) and the returned JSON data.

***

## 6. Instructing Your AI Agent in the System Prompt

While Gemini will automatically detect tools based on their description, mentioning them in your **System Prompt & Rules** ensures strict, deterministic workflow execution:

```markdown theme={null}
# APPOINTMENT BOOKING WORKFLOW:
1. Greet the customer and understand their requirement.
2. Ask for their preferred date and time.
3. Once they provide the date and time, IMMEDIATELY call the `check_slot_availability` tool.
4. If the tool confirms the slot is available, ask: "Would you like me to book this for you?".
5. If they confirm, trigger the `trigger_n8n_lead` tool with their name and contact details.
```

***

## 7. Connecting to n8n Webhooks

You can trigger any n8n workflow live during a call:

1. In n8n, create a **Webhook** node with method `POST`.
2. Copy the **Production Webhook URL** (e.g., `https://your-n8n.app/webhook/voice-lead`).
3. In Trikon Voice **Custom Tools**, add a new tool:
   * **Method**: `POST`
   * **URL**: Your n8n webhook URL
   * **Parameters**: `customer_name`, `intent`, `phone_number`
4. When the caller speaks, n8n receives the live payload instantly and continues your automation flow (sending WhatsApp messages, updating Google Sheets, notifying Slack, etc.).