---
sidebar_position: 10
title: Voice Agents
description: Create and manage AI-powered voice agents for automated customer interactions with versioned settings, real-time voice capabilities, and tool function calling.
---

# Voice Agents

Voice Agents are AI-powered bots that handle customer calls autonomously using real-time speech processing. They integrate LLM models with text-to-speech and speech-to-text capabilities to have natural conversations with callers.

Voice Agents use a **versioned settings** model — you can create multiple versions of your agent's configuration, test them, and publish the best one for production. Agents can also execute **Tools (Function Calling)** to perform telephony actions (transfers, hangups, SMS) or query external APIs via Webhooks in real time.

## Endpoints

| Method   | Endpoint                             | Description                           |
| -------- | ------------------------------------ | ------------------------------------- |
| `GET`    | `/voice-agents`                      | List all voice agents                 |
| `GET`    | `/voice-agents/:id`                  | Get voice agent details with settings |
| `POST`   | `/voice-agents`                      | Create a voice agent                  |
| `PATCH`  | `/voice-agents/:id`                  | Update voice agent name               |
| `DELETE` | `/voice-agents/:id`                  | Delete a voice agent                  |
| `GET`    | `/voice-agents/:id/versions`         | List all setting versions             |
| `PATCH`  | `/voice-agents/:id/settings`         | Update settings for a version         |
| `PATCH`  | `/voice-agents/:id/publish`          | Publish a settings version            |
| `POST`   | `/voice-agents/:id/version`          | Create a new settings version         |
| `DELETE` | `/voice-agents/:id/version/:version` | Delete a settings version             |
| `GET`    | `/voice-agents/:id/tools`            | List all tools configured for agent   |
| `GET`    | `/voice-agents/:id/tools/:toolId`    | Get a specific tool                   |
| `POST`   | `/voice-agents/:id/tools`            | Create a custom webhook tool          |
| `PATCH`  | `/voice-agents/:id/tools/:toolId`    | Update a tool                         |
| `DELETE` | `/voice-agents/:id/tools/:toolId`    | Delete a custom tool                  |
| `GET`    | `/voice-agents/models`               | List available AI models              |
| `GET`    | `/voice-agents/voices`               | List available TTS voices             |

## The Voice Agent Object

| Field               | Type   | Description                                        |
| ------------------- | ------ | -------------------------------------------------- |
| `id`                | string | Unique voice agent identifier                      |
| `name`              | string | Voice agent name                                   |
| `workspace_id`      | string | Workspace identifier                               |
| `country_code`      | string | Country code inherited from workspace              |
| `published_version` | number | Currently published settings version               |
| `settings`          | object | The settings object (included in detail responses) |
| `created_at`        | string | ISO 8601 creation timestamp                        |
| `updated_at`        | string | ISO 8601 last update timestamp                     |

### Voice Agent Settings Object

| Field                       | Type           | Description                                     |
| --------------------------- | -------------- | ----------------------------------------------- |
| `id`                        | string         | Unique settings record ID                       |
| `voice_agent_id`            | string         | Parent voice agent ID                           |
| `workspace_id`              | string         | Workspace identifier                            |
| `provider`                  | string         | AI provider (e.g., `openai`, `cartesia`)        |
| `model_id`                  | string         | AI model ID (e.g., `gpt-realtime-2.1`)          |
| `voice_id`                  | string \| null | TTS voice ID (e.g., `alloy`, `echo`, `shimmer`) |
| `greeting_message`          | string         | Initial greeting when call connects             |
| `instructions`              | string         | System prompt / behavior instructions           |
| `temperature`               | number         | Model creativity (default: `0.8`)               |
| `enable_noise_reduction`    | boolean        | Background noise reduction enabled              |
| `max_call_duration_seconds` | number         | Maximum call duration (0–1800 seconds)          |
| `tools_id`                  | string[]       | IDs of enabled tools/functions for this version |
| `version`                   | number         | Settings version number                         |
| `created_at`                | string         | ISO 8601 creation timestamp                     |
| `updated_at`                | string         | ISO 8601 last update timestamp                  |

### The Voice Agent Tool Object

| Field             | Type                            | Description                                                                         |
| ----------------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| `id`              | string                          | Unique tool identifier (e.g., `vat_abc123`)                                         |
| `voice_agent_id`  | string                          | Parent voice agent ID                                                               |
| `workspace_id`    | string                          | Workspace identifier                                                                |
| `name`            | string                          | Function calling name (lowercase alphanumeric with underscores, e.g. `check_order`) |
| `description`     | string                          | Description of what the tool does (used by LLM to decide when to call it)           |
| `tool_type`       | string                          | `builtin` (native telephony actions) or `custom` (external HTTP webhook)            |
| `webhook_url`     | string \| null                  | Target endpoint URL for custom webhook tools                                        |
| `webhook_method`  | string                          | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Default: `POST`              |
| `webhook_headers` | object                          | Custom key-value HTTP headers sent with the webhook request                         |
| `parameters`      | Record\<string, ToolParameter\> | Parameter schemas expected by the tool function                                     |
| `required_params` | string[]                        | Array of required parameter names                                                   |
| `is_active`       | boolean                         | Whether this tool is currently enabled for execution                                |
| `created_at`      | string                          | ISO 8601 creation timestamp                                                         |
| `updated_at`      | string                          | ISO 8601 last update timestamp                                                      |

#### Tool Parameter Schema

| Field         | Type     | Description                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------- |
| `type`        | string   | Parameter type: `string`, `number`, `integer`, `boolean`, `array`, `object` |
| `description` | string   | Description explaining the parameter's purpose to the LLM                   |
| `enum`        | string[] | Optional array of allowed values                                            |
| `required`    | boolean  | Whether this parameter is mandatory                                         |

---

## List Voice Agents

```
GET /voice-agents
```

Retrieve a paginated list of all voice agents in the workspace.

### Authentication

Requires `ApiKey` with any scope.

### Query Parameters

| Parameter    | Type   | Default      | Description                               |
| ------------ | ------ | ------------ | ----------------------------------------- |
| `page`       | number | `1`          | Page number                               |
| `limit`      | number | `10`         | Items per page (max: 100)                 |
| `search`     | string | —            | Search by name                            |
| `sort_field` | string | `created_at` | Sort field. Allowed: `created_at`, `name` |
| `sort_order` | string | `desc`       | Sort order: `asc` or `desc`               |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents?page=1&limit=10" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
      "name": "Support Assistant",
      "workspace_id": "yourcompany",
      "country_code": "US",
      "published_version": 2,
      "created_at": "2026-01-15T08:30:00.000Z",
      "updated_at": "2026-03-20T14:00:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

---

## Get Voice Agent

```
GET /voice-agents/:id
```

Retrieve a voice agent with its settings. By default returns the latest settings version. Optionally specify a version number.

### Authentication

Requires `ApiKey` with any scope.

### Path Parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| `id`      | string | The voice agent ID |

### Query Parameters

| Parameter | Type   | Description                                                            |
| --------- | ------ | ---------------------------------------------------------------------- |
| `version` | number | Specific settings version to retrieve. Defaults to the latest version. |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

```json
{
  "id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
  "name": "Support Assistant",
  "workspace_id": "yourcompany",
  "country_code": "US",
  "published_version": 2,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-20T14:00:00.000Z",
  "settings": {
    "id": "vas_a1b2c3d4e5f6a7b8c9d0e1f2",
    "voice_agent_id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
    "workspace_id": "yourcompany",
    "model_id": "gpt-realtime",
    "voice_id": "alloy",
    "greeting_message": "Thank you for calling Acme Corp. This is Support Assistant. How may I help you today?",
    "instructions": "You are a helpful customer support agent for Acme Corp...",
    "temperature": 0.8,
    "enable_noise_reduction": true,
    "max_call_duration_seconds": 180,
    "tools_id": [],
    "version": 2,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-03-20T14:00:00.000Z"
  }
}
```

### Error Response

```json
{
  "statusCode": 404,
  "message": "Voice Agent not found",
  "error": "Not Found"
}
```

---

## Create Voice Agent

```
POST /voice-agents
```

Create a new voice agent with initial instructions. A default settings version (v1) is automatically created with sensible defaults.

### Authentication

Requires `ApiKey` with `full` scope.

:::caution
Each workspace is limited to a maximum of **30 voice agents**.
:::

### Request Body

| Field          | Type   | Required | Description                                                 |
| -------------- | ------ | -------- | ----------------------------------------------------------- |
| `name`         | string | ✅       | Voice agent name. 3–30 characters.                          |
| `instructions` | string | ✅       | System prompt / behavior instructions. 10–3,500 characters. |
| `conversation` | string | —        | AI conversation ID from instruction generation flow.        |
| `response_id`  | string | —        | AI response ID from instruction generation flow.            |

### Default Settings

When a voice agent is created, the following defaults are applied to the initial settings:

| Setting                     | Default Value                                      |
| --------------------------- | -------------------------------------------------- |
| `model_id`                  | `gpt-realtime`                                     |
| `voice_id`                  | `null` (system default)                            |
| `temperature`               | `0.8`                                              |
| `enable_noise_reduction`    | `true`                                             |
| `max_call_duration_seconds` | `180` (3 minutes)                                  |
| `greeting_message`          | Auto-generated from workspace title and agent name |

### Request

```bash
curl -X POST "https://{workspace_id}.firetell.app/api/v1/voice-agents" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "instructions": "You are a sales assistant for Acme Corp. Help customers learn about our products and pricing. Always be professional and helpful. If a customer wants to speak with a human agent, transfer the call immediately."
  }'
```

### Response

```json
{
  "id": "va_d4e5f6a7-b8c9-d0e1-f2a3-b4c5d6e7f8a9",
  "name": "Sales Bot",
  "workspace_id": "yourcompany",
  "country_code": "US",
  "published_version": 1,
  "created_at": "2026-07-09T08:00:00.000Z",
  "updated_at": "2026-07-09T08:00:00.000Z"
}
```

### Error Response

```json
{
  "statusCode": 403,
  "message": "You have reached the maximum limit of 30 voice agents. Please contact support",
  "error": "Forbidden"
}
```

---

## Update Voice Agent

```
PATCH /voice-agents/:id
```

Update a voice agent's name. To update settings (instructions, model, voice, etc.), use the [Update Settings](#update-voice-agent-settings) endpoint.

### Authentication

Requires `ApiKey` with `full` scope.

### Request Body

| Field  | Type   | Required | Description                |
| ------ | ------ | -------- | -------------------------- |
| `name` | string | —        | New name. 3–30 characters. |

### Request

```bash
curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Support Bot"
  }'
```

### Response

Returns the full voice agent object with current settings (same format as [Get Voice Agent](#get-voice-agent)).

---

## Delete Voice Agent

```
DELETE /voice-agents/:id
```

Permanently delete a voice agent and all its settings versions.

### Authentication

Requires `ApiKey` with `full` scope.

:::caution
This action is irreversible. The voice agent and all its versioned settings will be permanently deleted.
:::

### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response

Returns the deleted voice agent object.

---

## Settings Version Management

Voice agents support **versioned settings**, allowing you to iterate on configurations and roll back if needed.

### List Versions

```
GET /voice-agents/:id/versions
```

List all settings versions for a voice agent, sorted by version number (newest first).

### Authentication

Requires `ApiKey` with any scope.

#### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/versions" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "version": 3,
      "updated_at": "2026-07-09T09:00:00.000Z"
    },
    {
      "version": 2,
      "updated_at": "2026-06-15T14:30:00.000Z"
    },
    {
      "version": 1,
      "updated_at": "2026-01-15T08:30:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

---

### Update Voice Agent Settings

```
PATCH /voice-agents/:id/settings
```

Update the settings of a specific version. You must specify the `version` number of the settings you want to modify.

### Authentication

Requires `ApiKey` with `full` scope.

#### Request Body

All fields are optional except `version`:

| Field                       | Type     | Required | Description                                  |
| --------------------------- | -------- | -------- | -------------------------------------------- |
| `version`                   | number   | ✅       | The settings version to update (min: 1)      |
| `greeting_message`          | string   | —        | Initial greeting. Max 250 characters.        |
| `instructions`              | string   | —        | System prompt. 10–3,500 characters.          |
| `model_id`                  | string   | —        | AI model ID. 1–100 characters.               |
| `voice_id`                  | string   | —        | TTS voice ID. 1–100 characters.              |
| `enable_noise_reduction`    | boolean  | —        | Enable noise reduction                       |
| `max_call_duration_seconds` | number   | —        | Max call duration. 0–1,800 seconds (30 min). |
| `functions`                 | string[] | —        | Array of tool/function IDs to enable         |

#### Request

```bash
curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/settings" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 2,
    "instructions": "Updated instructions for the voice agent...",
    "voice_id": "shimmer",
    "max_call_duration_seconds": 300,
    "enable_noise_reduction": true
  }'
```

#### Response

Returns the full voice agent object with the updated settings version.

---

### Publish a Version

```
PATCH /voice-agents/:id/publish
```

Publish a settings version to make it the active configuration used for live calls.

### Authentication

Requires `ApiKey` with `full` scope.

#### Request Body

| Field     | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `version` | number | ✅       | The version number to publish (min: 1) |

#### Request

```bash
curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/publish" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3
  }'
```

#### Response

Returns the full voice agent object with `published_version` updated.

---

### Create a New Version

```
POST /voice-agents/:id/version
```

Create a new settings version by cloning the currently published version. The new version gets the next sequential version number.

### Authentication

Requires `ApiKey` with `full` scope.

:::info

- You must have at least one **published** version before creating a new version.
- A maximum of **20 versions** are kept. Older versions are automatically cleaned up.
  :::

#### Request

```bash
curl -X POST "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/version" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

#### Response

```json
{
  "version": 4,
  "updated_at": "2026-07-09T10:00:00.000Z"
}
```

#### Error Responses

```json
{
  "statusCode": 400,
  "message": "You must publish one version before creating another",
  "error": "Bad Request"
}
```

---

### Delete a Version

```
DELETE /voice-agents/:id/version/:version
```

Delete a specific settings version. You cannot delete the currently published version.

### Authentication

Requires `ApiKey` with `full` scope.

#### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/version/3" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

#### Response

```json
{
  "version": 3,
  "updated_at": "2026-07-09T09:00:00.000Z"
}
```

#### Error Response

```json
{
  "statusCode": 400,
  "message": "Version has been Published, You cannot delete",
  "error": "Bad Request"
}
```

---

## Voice Agent Tools (Function Calling)

Voice Agent Tools allow your AI agent to take concrete actions during live phone conversations using **Function Calling**.

There are two categories of tools:

1. **Built-in Telephony Tools**: Native actions executed directly on the Firetell telephony switch (e.g. hang up, transfer call, send SMS).
2. **Custom Webhook Tools**: External API integrations. When the AI decides to query an order, check account balance, or book an appointment, Firetell dispatches an HTTP request to your webhook URL and provides the JSON response back to the LLM to speak naturally to the caller.

---

### Built-in Telephony Tools Reference

Built-in tools are pre-configured in every workspace and executed directly on the Firetell telephony switch:

| Tool Name        | Parameters                                                                                                                                                                                                   | Description                                                                                           |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| `transfer_call`  | `to` _(string, required)_: Phone number (`"+14155552671"`), agent extension (`"agent-ag_005"`), or team name (`"team-te_001"`).<br/>`reason` _(string, optional)_: Brief reason for transfer.                | Transfer the current call to another destination (external phone number, agent extension, or queue).  |
| `end_call`       | `reason` _(string, optional)_: Brief reason for ending the call (e.g. `"Conversation completed"`).                                                                                                           | Gracefully terminates the phone call when the conversation is finished or caller requests to hang up. |
| `hold_call`      | `action` _(string, required, enum: `["hold", "resume"]`)_: Whether to put on hold or resume.                                                                                                                 | Place the caller on hold (or resume call) while looking up information or consulting team members.    |
| `collect_digits` | `prompt` _(string, required)_: Prompt to say before collecting digits.<br/>`max_digits` _(string, required)_: Max digits (1–20).<br/>`timeout_seconds` _(string, optional, default: `10`)_: Seconds to wait. | Ask the caller to enter DTMF digits using their keypad (e.g. account numbers, OTP, PIN).              |
| `send_dtmf`      | `digits` _(string, required)_: DTMF digits string (e.g. `"1234#"` or `"0"`).                                                                                                                                 | Send DTMF keypad tones to the remote end (useful for navigating IVR menus).                           |

---

### Custom Webhook Tools Architecture

When an agent invokes a Custom Webhook Tool, the call flow works as follows:

```
[Caller speaks: "Where is order ORD-9988?"]
                  │
                  ▼
         [AI Voice Agent (LLM)]
  (Determines it needs to call check_order)
                  │
                  ▼
       [Firetell AI Gateway]
                  │ HTTP POST
                  ▼
       [Your Webhook Endpoint]
  https://api.yourcompany.com/tools/orders
                  │
                  │ Returns JSON:
                  │ { "status": "Shipped", "eta": "Tomorrow by 2 PM" }
                  ▼
       [Firetell AI Gateway]
  (Feeds response back to AI Model)
                  │
                  ▼
[AI speaks: "Your order has shipped and will arrive tomorrow by 2 PM!"]
```

#### 1. Webhook Request Sent by Firetell

When a custom tool is triggered, Firetell makes an HTTP request to your configured `webhook_url`:

##### HTTP Headers:

```http
Content-Type: application/json
User-Agent: Firetell-Voice-Agent-Webhook/1.0
X-Workspace-Id: ws_f82a1c4b9d0e
X-Call-Id: call_1787334135262_26bqsku
X-Caller-Number: +14155552671
X-Caller-Name: John%20Doe
X-Called-Number: +18005550199
X-Voice-Agent-Id: va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c
X-Voice-Agent-Name: Customer%20Support%20Agent
```

_(Plus any custom headers defined in `webhook_headers`, such as `Authorization: Bearer YOUR_SECRET`)_

##### Request Body (for `POST`, `PUT`, `PATCH`):

```json
{
  "event": "tool_call",
  "timestamp": "2026-08-22T01:45:00.000Z",
  "workspace_id": "ws_f82a1c4b9d0e",
  "call_id": "call_1787334135262_26bqsku",
  "caller": {
    "number": "+14155552671",
    "name": "John Doe"
  },
  "called_number": "+18005550199",
  "voice_agent": {
    "id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
    "name": "Customer Support Agent"
  },
  "tool": {
    "id": "vat_9b2e4a1f",
    "name": "check_order_status"
  },
  "arguments": {
    "order_id": "ORD-9988"
  }
}
```

:::note
For `GET` requests, arguments are passed as URL query parameters (e.g. `?order_id=ORD-9988`).
:::

#### 2. Expected Webhook Response

Your webhook should respond with **HTTP 200 OK** and a JSON object or string containing the result:

```json
{
  "order_id": "ORD-9988",
  "status": "Shipped",
  "carrier": "FedEx",
  "tracking_number": "123456789012",
  "estimated_delivery": "Tomorrow by 2:00 PM"
}
```

#### 3. Execution Constraints & Best Practices:

- **Timeout**: Firetell waits up to **8.0 seconds** for webhook responses before timing out. For optimal real-time conversational latency, ensure your webhook responds within **500–1500 ms**.
- **Max Response Size**: Maximum **100 KB** per response payload.
- **Error Fallback**: If your webhook returns HTTP 4xx/5xx or times out, Firetell returns an error message to the LLM so it can politely inform the caller (e.g., _"I'm having trouble looking up that order right now. Let me connect you with a representative."_).

---

## Tool Management Endpoints

### List Tools for a Voice Agent

```
GET /voice-agents/:id/tools
```

Retrieve a list of all tools (both built-in and custom) available for a specific voice agent.

#### Authentication

Requires `ApiKey` with any scope.

#### Query Parameters

| Parameter    | Type   | Default      | Description                               |
| ------------ | ------ | ------------ | ----------------------------------------- |
| `page`       | number | `1`          | Page number                               |
| `limit`      | number | `50`         | Items per page (max: 100)                 |
| `search`     | string | —            | Search tools by name or description       |
| `sort_field` | string | `created_at` | Sort field. Allowed: `created_at`, `name` |
| `sort_order` | string | `desc`       | Sort order: `asc` or `desc`               |

#### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/tools" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "vat_9b2e4a1f",
      "voice_agent_id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
      "workspace_id": "yourcompany",
      "name": "check_order_status",
      "description": "Check order shipping status and estimated delivery time by order ID",
      "tool_type": "custom",
      "webhook_url": "https://api.yourdomain.com/tools/check-order",
      "webhook_method": "POST",
      "webhook_headers": {
        "Authorization": "Bearer sec_live_998877"
      },
      "parameters": {
        "order_id": {
          "type": "string",
          "description": "The customer order reference code (e.g. ORD-12345)",
          "required": true
        }
      },
      "required_params": ["order_id"],
      "is_active": true,
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-03-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "total_pages": 1
  }
}
```

---

### Get a Specific Tool

```
GET /voice-agents/:id/tools/:toolId
```

Retrieve details of a specific tool.

#### Authentication

Requires `ApiKey` with any scope.

#### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/tools/vat_9b2e4a1f" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

---

### Create a Custom Tool

```
POST /voice-agents/:id/tools
```

Create a new custom webhook tool for a voice agent.

#### Authentication

Requires `ApiKey` with `full` scope.

#### Request Body

| Field             | Type                            | Required | Description                                                                          |
| ----------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `name`            | string                          | ✅       | Function name (lowercase alphanumeric with underscores, regex `/^[a-z][a-z0-9_]*$/`) |
| `description`     | string                          | ✅       | Clear description for the LLM to know when and how to call this tool (5–1000 chars)  |
| `webhook_url`     | string                          | —        | Target HTTPS endpoint for the webhook                                                |
| `webhook_method`  | string                          | —        | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Default: `POST`                |
| `webhook_headers` | Record\<string, string\>        | —        | Custom request headers (e.g. authorization tokens)                                   |
| `parameters`      | Record\<string, ToolParameter\> | —        | JSON schema definition of input arguments expected from the LLM                      |
| `required_params` | string[]                        | —        | List of mandatory parameter keys                                                     |
| `is_active`       | boolean                         | —        | Whether the tool is active immediately (default: `true`)                             |

#### Request

```bash
curl -X POST "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/tools" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "book_appointment",
    "description": "Book a service technician appointment for a customer given a date and time slot",
    "webhook_url": "https://api.yourdomain.com/appointments/book",
    "webhook_method": "POST",
    "webhook_headers": {
      "Authorization": "Bearer sec_live_token"
    },
    "parameters": {
      "service_type": {
        "type": "string",
        "description": "Type of service needed (e.g. internet_repair, router_installation)"
      },
      "preferred_date": {
        "type": "string",
        "description": "Date in YYYY-MM-DD format"
      },
      "time_slot": {
        "type": "string",
        "description": "Morning (9am-12pm) or Afternoon (1pm-5pm)",
        "enum": ["morning", "afternoon"]
      }
    },
    "required_params": ["service_type", "preferred_date", "time_slot"],
    "is_active": true
  }'
```

#### Response

```json
{
  "id": "vat_e81c02ab",
  "voice_agent_id": "va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c",
  "workspace_id": "yourcompany",
  "name": "book_appointment",
  "description": "Book a service technician appointment for a customer given a date and time slot",
  "tool_type": "custom",
  "webhook_url": "https://api.yourdomain.com/appointments/book",
  "webhook_method": "POST",
  "webhook_headers": {
    "Authorization": "Bearer sec_live_token"
  },
  "parameters": {
    "service_type": {
      "type": "string",
      "description": "Type of service needed (e.g. internet_repair, router_installation)"
    },
    "preferred_date": {
      "type": "string",
      "description": "Date in YYYY-MM-DD format"
    },
    "time_slot": {
      "type": "string",
      "description": "Morning (9am-12pm) or Afternoon (1pm-5pm)",
      "enum": ["morning", "afternoon"]
    }
  },
  "required_params": ["service_type", "preferred_date", "time_slot"],
  "is_active": true,
  "created_at": "2026-08-22T01:45:00.000Z",
  "updated_at": "2026-08-22T01:45:00.000Z"
}
```

---

### Update a Tool

```
PATCH /voice-agents/:id/tools/:toolId
```

Update properties of an existing tool.

:::note

- For **Custom Tools**: All fields including `name`, `description`, `webhook_url`, `webhook_headers`, and `parameters` can be updated.
- For **Built-in Tools**: Only `is_active` and `description` can be modified.
  :::

#### Authentication

Requires `ApiKey` with `full` scope.

#### Request

```bash
curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/tools/vat_e81c02ab" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Book or reschedule a service technician appointment",
    "is_active": true
  }'
```

---

### Delete a Custom Tool

```
DELETE /voice-agents/:id/tools/:toolId
```

Permanently remove a custom webhook tool. Built-in telephony tools cannot be deleted (use `is_active: false` to disable them instead).

#### Authentication

Requires `ApiKey` with `full` scope.

#### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/voice-agents/va_7f3a2b1c-9d4e-5f6a-8b0c-1d2e3f4a5b6c/tools/vat_e81c02ab" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

#### Response

```json
{
  "id": "vat_e81c02ab",
  "name": "book_appointment",
  "deleted": true
}
```

---

## Catalog Endpoints

### List AI Models

```
GET /voice-agents/models
```

List available AI models that can be used for voice agents.

### Authentication

Requires `ApiKey` with any scope.

#### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/models" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

---

### List TTS Voices

```
GET /voice-agents/voices
```

List available text-to-speech voices, filtered by the workspace's country code.

### Authentication

Requires `ApiKey` with any scope.

#### Query Parameters

| Parameter  | Type   | Description                                  |
| ---------- | ------ | -------------------------------------------- |
| `model_id` | string | Filter voices by model. Max 100 characters.  |
| `provider` | string | Filter by voice provider. Max 50 characters. |
| `page`     | number | Page number                                  |
| `limit`    | number | Items per page                               |
| `search`   | string | Search voices by name                        |

#### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/voice-agents/voices?provider=openai" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```