Skip to main content
🤖 LLM Friendly: This page is available in raw Markdown format for LLM consumption:voice-agents.md|Get full documentation:llms.txt/llms-full.txt

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​

MethodEndpointDescription
GET/voice-agentsList all voice agents
GET/voice-agents/:idGet voice agent details with settings
POST/voice-agentsCreate a voice agent
PATCH/voice-agents/:idUpdate voice agent name
DELETE/voice-agents/:idDelete a voice agent
GET/voice-agents/:id/versionsList all setting versions
PATCH/voice-agents/:id/settingsUpdate settings for a version
PATCH/voice-agents/:id/publishPublish a settings version
POST/voice-agents/:id/versionCreate a new settings version
DELETE/voice-agents/:id/version/:versionDelete a settings version
GET/voice-agents/:id/toolsList all tools configured for agent
GET/voice-agents/:id/tools/:toolIdGet a specific tool
POST/voice-agents/:id/toolsCreate a custom webhook tool
PATCH/voice-agents/:id/tools/:toolIdUpdate a tool
DELETE/voice-agents/:id/tools/:toolIdDelete a custom tool
GET/voice-agents/modelsList available AI models
GET/voice-agents/voicesList available TTS voices

The Voice Agent Object​

FieldTypeDescription
idstringUnique voice agent identifier
namestringVoice agent name
workspace_idstringWorkspace identifier
country_codestringCountry code inherited from workspace
published_versionnumberCurrently published settings version
settingsobjectThe settings object (included in detail responses)
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last update timestamp

Voice Agent Settings Object​

FieldTypeDescription
idstringUnique settings record ID
voice_agent_idstringParent voice agent ID
workspace_idstringWorkspace identifier
providerstringAI provider (e.g., openai, cartesia)
model_idstringAI model ID (e.g., gpt-realtime-2.1)
voice_idstring | nullTTS voice ID (e.g., alloy, echo, shimmer)
greeting_messagestringInitial greeting when call connects
instructionsstringSystem prompt / behavior instructions
temperaturenumberModel creativity (default: 0.8)
enable_noise_reductionbooleanBackground noise reduction enabled
max_call_duration_secondsnumberMaximum call duration (0–1800 seconds)
tools_idstring[]IDs of enabled tools/functions for this version
versionnumberSettings version number
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last update timestamp

The Voice Agent Tool Object​

FieldTypeDescription
idstringUnique tool identifier (e.g., vat_abc123)
voice_agent_idstringParent voice agent ID
workspace_idstringWorkspace identifier
namestringFunction calling name (lowercase alphanumeric with underscores, e.g. check_order)
descriptionstringDescription of what the tool does (used by LLM to decide when to call it)
tool_typestringbuiltin (native telephony actions) or custom (external HTTP webhook)
webhook_urlstring | nullTarget endpoint URL for custom webhook tools
webhook_methodstringHTTP method (GET, POST, PUT, PATCH, DELETE). Default: POST
webhook_headersobjectCustom key-value HTTP headers sent with the webhook request
parametersRecord<string, ToolParameter>Parameter schemas expected by the tool function
required_paramsstring[]Array of required parameter names
is_activebooleanWhether this tool is currently enabled for execution
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last update timestamp

Tool Parameter Schema​

FieldTypeDescription
typestringParameter type: string, number, integer, boolean, array, object
descriptionstringDescription explaining the parameter's purpose to the LLM
enumstring[]Optional array of allowed values
requiredbooleanWhether 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​

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber10Items per page (max: 100)
searchstring—Search by name
sort_fieldstringcreated_atSort field. Allowed: created_at, name
sort_orderstringdescSort order: asc or desc

Request​

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

Response​

{
  "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​

ParameterTypeDescription
idstringThe voice agent ID

Query Parameters​

ParameterTypeDescription
versionnumberSpecific settings version to retrieve. Defaults to the latest version.

Request​

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​

{
  "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​

{
  "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​

FieldTypeRequiredDescription
namestring✅Voice agent name. 3–30 characters.
instructionsstring✅System prompt / behavior instructions. 10–3,500 characters.
conversationstring—AI conversation ID from instruction generation flow.
response_idstring—AI response ID from instruction generation flow.

Default Settings​

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

SettingDefault Value
model_idgpt-realtime
voice_idnull (system default)
temperature0.8
enable_noise_reductiontrue
max_call_duration_seconds180 (3 minutes)
greeting_messageAuto-generated from workspace title and agent name

Request​

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​

{
  "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​

{
  "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 endpoint.

Authentication​

Requires ApiKey with full scope.

Request Body​

FieldTypeRequiredDescription
namestring—New name. 3–30 characters.

Request​

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).

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​

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​

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​

{
  "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:

FieldTypeRequiredDescription
versionnumber✅The settings version to update (min: 1)
greeting_messagestring—Initial greeting. Max 250 characters.
instructionsstring—System prompt. 10–3,500 characters.
model_idstring—AI model ID. 1–100 characters.
voice_idstring—TTS voice ID. 1–100 characters.
enable_noise_reductionboolean—Enable noise reduction
max_call_duration_secondsnumber—Max call duration. 0–1,800 seconds (30 min).
functionsstring[]—Array of tool/function IDs to enable

Request​

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​

FieldTypeRequiredDescription
versionnumber✅The version number to publish (min: 1)

Request​

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​

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​

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

Error Responses​

{
  "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​

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​

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

Error Response​

{
  "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 NameParametersDescription
transfer_callto (string, required): Phone number ("+14155552671"), agent extension ("agent-ag_005"), or team name ("team-te_001").
reason (string, optional): Brief reason for transfer.		Transfer the current call to another destination (external phone number, agent extension, or queue).
end_callreason (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_callaction (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_digitsprompt (string, required): Prompt to say before collecting digits.
max_digits (string, required): Max digits (1–20).
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_dtmfdigits (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:​
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):​
{
  "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:

{
  "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​

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber50Items per page (max: 100)
searchstring—Search tools by name or description
sort_fieldstringcreated_atSort field. Allowed: created_at, name
sort_orderstringdescSort order: asc or desc

Request​

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​

{
  "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​

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​

FieldTypeRequiredDescription
namestring✅Function name (lowercase alphanumeric with underscores, regex /^[a-z][a-z0-9_]*$/)
descriptionstring✅Clear description for the LLM to know when and how to call this tool (5–1000 chars)
webhook_urlstring—Target HTTPS endpoint for the webhook
webhook_methodstring—HTTP method: GET, POST, PUT, PATCH, DELETE. Default: POST
webhook_headersRecord<string, string>—Custom request headers (e.g. authorization tokens)
parametersRecord<string, ToolParameter>—JSON schema definition of input arguments expected from the LLM
required_paramsstring[]—List of mandatory parameter keys
is_activeboolean—Whether the tool is active immediately (default: true)

Request​

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​

{
  "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​

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​

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​

{
  "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​

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​

ParameterTypeDescription
model_idstringFilter voices by model. Max 100 characters.
providerstringFilter by voice provider. Max 50 characters.
pagenumberPage number
limitnumberItems per page
searchstringSearch voices by name

Request​

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