Update Voice Agent Tools

Overview

Voice agents can be enhanced with tools that enable advanced functionality during calls:

End calls gracefully when objectives are met
Transfer calls to human agents or phone numbers
Integrate with external APIs (CRM, databases, etc.)
Book appointments via Cal.com
Send SMS messages during calls
Transfer to other AI agents for specialized handling
Extract and save conversation data
Navigate IVR systems with DTMF
And more!

Tools are only supported for voice agents. SMS agents do not support tools.

Authentication

X-API-Key

string

required

Your Teli API key

Path Parameters

agent_id

string

required

The unique identifier of the voice agent to update

Request Body

tools

array

required

Array of tool configurations. Each tool must have type, name, and type-specific fields.

Supported Tool Types

1. End Call

End the conversation gracefully when objectives are met.

{
  "type": "end_call",
  "name": "end_conversation",
  "description": "End the call when the customer's questions are answered"
}

type

string

required

Must be "end_call"

name

string

required

Unique tool name (snake_case, a-z, 0-9, underscores only)

description

string

What the tool does and when to use it

2. Transfer Call

Transfer the call to a human agent or phone number.

{
  "type": "transfer_call",
  "name": "transfer_to_support",
  "description": "Transfer to human support team when user requests assistance",
  "transfer_destination": {
    "type": "predefined",
    "number": "+15551234567"
  },
  "transfer_option": {
    "type": "cold_transfer"
  }
}

transfer_destination

object

required

Where to transfer the callProperties:

type: Must be "predefined"
number: Phone number in E.164 format (e.g., "+15551234567")
extension (optional): Extension digits (e.g., "123")

transfer_option

object

required

How to transfer the callProperties:

type: "cold_transfer" (immediate) or "warm_transfer" (AI introduces)
on_hold_music (warm only): "none", "relaxing_sound", "uplifting_beats", "ringtone"
show_transferee_as_caller (optional): Show caller’s number to transfer destination

3. Custom API Integration

Integrate with any external API (CRM, databases, order systems, etc.)

{
  "type": "custom",
  "name": "check_order_status",
  "description": "Check order status in CRM when customer provides order number",
  "url": "https://api.yourcrm.com/orders/{{order_id}}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "speak_after_execution": true
}

url

string

required

API endpoint URL. Supports dynamic variables: {{variable_name}}

method

string

required

HTTP method: "GET", "POST", "PUT", "PATCH", or "DELETE"

headers

object

HTTP headers (e.g., authorization, content-type)

query_params

object

Query parameters to append to URL

speak_after_execution

boolean

required

Whether AI should speak the result after API call completes

4. Check Calendar Availability (Cal.com)

Check available time slots in Cal.com calendar.

{
  "type": "check_availability_cal",
  "name": "check_doctor_availability",
  "description": "Check available appointment slots for doctor",
  "cal_api_key": "cal_live_xxxxxxxxxxxx",
  "event_type_id": 60444,
  "timezone": "America/Los_Angeles"
}

cal_api_key

string

required

Cal.com API key (get from Cal.com dashboard → Settings → Developer → API Keys)

event_type_id

number

required

Cal.com event type ID (found in event type URL)

timezone

string

IANA timezone (e.g., "America/New_York", "Europe/London"). If not specified, uses caller’s timezone or server default.

5. Book Appointment (Cal.com)

Book appointments directly via Cal.com.

{
  "type": "book_appointment_cal",
  "name": "book_consultation",
  "description": "Book a 30-minute consultation appointment",
  "cal_api_key": "cal_live_xxxxxxxxxxxx",
  "event_type_id": 60444,
  "timezone": "America/New_York"
}

cal_api_key

string

required

Cal.com API key

event_type_id

number

required

Cal.com event type ID

timezone

string

IANA timezone for booking

6. Agent Transfer

Transfer conversation to another AI agent (not a phone transfer).

{
  "type": "agent_swap",
  "name": "transfer_to_booking_agent",
  "description": "Transfer to specialized booking agent",
  "agent_id": "agent_xxxxxxxxxxxxxxxxxx",
  "post_call_analysis_setting": "both_agents"
}

agent_id

string

required

ID of the target AI agent to transfer to

post_call_analysis_setting

string

required

"both_agents" or "only_destination_agent"

agent_version

number

Specific version of target agent. If not specified, uses latest.

Agent Transfer vs Phone Transfer: Agent transfer switches AI handlers instantly with full conversation history, while phone transfer creates a new phone call. Agent transfer is faster and more reliable.

7. Send SMS

Send one-way SMS message during voice call.

{
  "type": "send_sms",
  "name": "send_confirmation",
  "description": "Send appointment confirmation via text",
  "sms_content": {
    "type": "predefined",
    "content": "Your appointment is confirmed for {{appointment_date}} at {{appointment_time}}. See you soon!"
  }
}

sms_content

object

required

SMS message configurationFor predefined messages:

type: "predefined"
content: The message text (supports dynamic variables like {{name}})

For AI-generated messages:

type: "inferred"
prompt: Instructions for AI to generate the message

SMS tools only work for phone numbers with SMS capability enabled.

8. Extract Dynamic Variables

Extract and save conversation data as variables for later use.

{
  "type": "extract_dynamic_variable",
  "name": "extract_customer_info",
  "description": "Extract customer name, phone, and email from conversation",
  "variables": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The customer's full name"
    },
    {
      "type": "string",
      "name": "customer_email",
      "description": "The customer's email address"
    },
    {
      "type": "enum",
      "name": "interest_level",
      "description": "Customer's interest level",
      "choices": ["high", "medium", "low"]
    }
  ]
}

variables

array

required

Variables to extract. Each variable has:

type: "string", "number", "enum", or "boolean"
name: Variable name (snake_case)
description: What to extract
choices (for enum): Array of possible values
examples (optional): Example values to guide AI

9. Press Digit (DTMF)

Press phone keypad digits for IVR navigation.

{
  "type": "press_digit",
  "name": "press_1_for_sales",
  "description": "Press 1 to navigate to sales department",
  "delay_ms": 1000
}

delay_ms

number

Delay in milliseconds before pressing digit (default: 1000ms, max: 5000ms)

Useful for navigating automated phone systems and IVR menus.

10. MCP (Model Context Protocol)

Connect to MCP servers for advanced integrations.

{
  "type": "mcp",
  "name": "inventory_lookup",
  "description": "Check inventory via MCP server",
  "mcp_id": "mcp_xxxxxxxxxxxx"
}

mcp_id

string

required

Unique ID of the MCP server configuration

MCP tools require prior MCP server configuration. Contact support for setup assistance.

Request Examples

Update with Single Tool

curl -X PATCH "https://api.teli.ai/v1/agents/1763763759612x739630924151608142/tools" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "type": "end_call",
        "name": "end_conversation",
        "description": "End the call when objectives are completed"
      }
    ]
  }'

Update with Multiple Tools

{
  "tools": [
    {
      "type": "custom",
      "name": "check_order_status",
      "description": "Check customer order status in CRM",
      "url": "https://api.yourcrm.com/orders/{{order_id}}",
      "method": "GET",
      "headers": {
        "Authorization": "Bearer YOUR_CRM_API_KEY"
      },
      "speak_after_execution": true
    },
    {
      "type": "transfer_call",
      "name": "transfer_to_support",
      "description": "Transfer to human support if customer is frustrated",
      "transfer_destination": {
        "type": "predefined",
        "number": "+15551234567"
      },
      "transfer_option": {
        "type": "warm_transfer"
      }
    },
    {
      "type": "send_sms",
      "name": "send_order_tracking",
      "description": "Send order tracking link via SMS",
      "sms_content": {
        "type": "predefined",
        "content": "Your order {{order_id}} is on the way! Track it here: {{tracking_url}}"
      }
    },
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call after helping customer"
    }
  ]
}

Healthcare Appointment Example

{
  "tools": [
    {
      "type": "check_availability_cal",
      "name": "check_appointment_slots",
      "description": "Check available appointment slots with Dr. Smith",
      "cal_api_key": "cal_live_xxxxxxxxxxxx",
      "event_type_id": 60444,
      "timezone": "America/Los_Angeles"
    },
    {
      "type": "book_appointment_cal",
      "name": "book_appointment",
      "description": "Book the appointment after customer confirms time",
      "cal_api_key": "cal_live_xxxxxxxxxxxx",
      "event_type_id": 60444,
      "timezone": "America/Los_Angeles"
    },
    {
      "type": "send_sms",
      "name": "send_appointment_confirmation",
      "description": "Send appointment confirmation via text",
      "sms_content": {
        "type": "predefined",
        "content": "Your appointment with Dr. Smith is confirmed for {{appointment_date}} at {{appointment_time}}. Reply CANCEL to cancel."
      }
    },
    {
      "type": "transfer_call",
      "name": "transfer_to_nurse",
      "description": "Transfer to nurse for medical questions",
      "transfer_destination": {
        "type": "predefined",
        "number": "+15559876543"
      },
      "transfer_option": {
        "type": "warm_transfer"
      }
    },
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End call after appointment is booked"
    }
  ]
}

Sales Bot Example

{
  "tools": [
    {
      "type": "custom",
      "name": "check_inventory",
      "description": "Check product inventory and pricing",
      "url": "https://api.yourstore.com/inventory/{{product_sku}}",
      "method": "GET",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "speak_after_execution": true
    },
    {
      "type": "custom",
      "name": "create_quote",
      "description": "Generate price quote for customer",
      "url": "https://api.yourcrm.com/quotes",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      "speak_after_execution": true
    },
    {
      "type": "send_sms",
      "name": "send_quote",
      "description": "Text the quote to customer",
      "sms_content": {
        "type": "predefined",
        "content": "Thanks for your interest! Your quote: {{quote_amount}}. Questions? Call us at +15551234567"
      }
    },
    {
      "type": "transfer_call",
      "name": "transfer_to_sales_rep",
      "description": "Transfer to human sales representative for closing",
      "transfer_destination": {
        "type": "predefined",
        "number": "+15551234567"
      },
      "transfer_option": {
        "type": "warm_transfer"
      }
    },
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End call after quote sent or sale completed"
    }
  ]
}

Response

Success Response

{
  "success": true,
  "agent_id": "1763763759612x739630924151608142",
  "tools_count": 5,
  "message": "Agent tools updated successfully",
  "powered_by": "Teli"
}

success

boolean

Indicates successful update

agent_id

string

The agent’s unique identifier

tools_count

number

Number of tools configured

message

string

Success message

powered_by

string

Platform identifier

Error Responses

{
  "error": "Agent not found",
  "success": false,
  "powered_by": "Teli"
}

Tool Naming Requirements

Tool names must follow these rules:

Lowercase letters only (a-z)
Numbers allowed (0-9)
Underscores allowed (_)
No spaces
No special characters
Maximum 64 characters

Examples:

✅ "end_call"
✅ "transfer_to_support"
✅ "check_order_status"
❌ "Transfer to Support" (spaces, capitals)
❌ "check-order" (hyphen not allowed)
❌ "send SMS!" (space, special char)

Our platform auto-sanitizes names, but following this format ensures consistency.

Dynamic Variables

Many tools support dynamic variables that get substituted at runtime from the conversation:

{
  "type": "custom",
  "name": "lookup_customer",
  "url": "https://api.crm.com/customers/{{customer_phone}}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {{api_key}}"
  },
  "speak_after_execution": true
}

Common variables:

{{first_name}}, {{last_name}}, {{customer_name}}
{{phone_number}}, {{email}}
{{order_id}}, {{appointment_date}}, {{appointment_time}}
Custom variables extracted during conversation

Best Practices

1. Tool Descriptions

Write clear descriptions that tell the AI when to use the tool:

{
  "type": "transfer_call",
  "name": "transfer_to_support",
  "description": "Transfer to human support ONLY if customer explicitly asks to speak with a person, or if they are frustrated and escalating"
}

2. Tool Combinations

Combine tools for powerful workflows: Support Bot:

check_order_status (Custom API)
transfer_to_support (Transfer)
end_call (End Call)

Booking Bot:

check_availability_cal (Check Calendar)
book_appointment_cal (Book Appointment)
send_confirmation (Send SMS)
end_call (End Call)

Sales Bot:

check_inventory (Custom API)
create_quote (Custom API)
send_quote (Send SMS)
transfer_to_sales_rep (Transfer)
end_call (End Call)

3. Error Handling

Tools can timeout or fail. Include fallback instructions in your agent prompt:

If the check_order_status tool fails or times out, apologize and offer to transfer 
to a human representative who can help.

4. Tool Naming

Use descriptive, action-oriented names:

✅ check_order_status
✅ book_appointment
✅ transfer_to_support
❌ tool1
❌ api_call
❌ function

Common Use Cases

Customer Support

{
  "tools": [
    {"type": "custom", "name": "check_account_status", ...},
    {"type": "custom", "name": "update_customer_info", ...},
    {"type": "send_sms", "name": "send_ticket_number", ...},
    {"type": "transfer_call", "name": "transfer_to_specialist", ...},
    {"type": "end_call", "name": "end_call", ...}
  ]
}

Healthcare

{
  "tools": [
    {"type": "check_availability_cal", "name": "check_doctor_slots", ...},
    {"type": "book_appointment_cal", "name": "book_appointment", ...},
    {"type": "send_sms", "name": "send_confirmation", ...},
    {"type": "transfer_call", "name": "transfer_to_nurse", ...},
    {"type": "end_call", "name": "end_call", ...}
  ]
}

Sales & Lead Qualification

{
  "tools": [
    {"type": "custom", "name": "check_pricing", ...},
    {"type": "custom", "name": "check_inventory", ...},
    {"type": "extract_dynamic_variable", "name": "save_lead_info", ...},
    {"type": "send_sms", "name": "send_brochure_link", ...},
    {"type": "transfer_call", "name": "transfer_to_sales", ...},
    {"type": "end_call", "name": "end_call", ...}
  ]
}

Appointment Scheduling

{
  "tools": [
    {"type": "check_availability_cal", "name": "check_slots", ...},
    {"type": "book_appointment_cal", "name": "book_slot", ...},
    {"type": "send_sms", "name": "send_calendar_invite", ...},
    {"type": "end_call", "name": "end_call", ...}
  ]
}

Response Examples

Successful Update

{
  "success": true,
  "agent_id": "1763763759612x739630924151608142",
  "tools_count": 4,
  "message": "Agent tools updated successfully",
  "powered_by": "Teli"
}

Error: Not a Voice Agent

{
  "error": "Tools are only supported for voice agents",
  "success": false,
  "powered_by": "Teli"
}

Tools are only available for voice agents. SMS agents use different mechanisms for automation.

Error: Agent Not Found

{
  "error": "Agent not found",
  "success": false,
  "powered_by": "Teli"
}

Error: Invalid Tool Configuration

{
  "error": "Failed to update agent tools",
  "success": false,
  "powered_by": "Teli"
}

Check tool names follow naming requirements (snake_case, no spaces). Our API auto-sanitizes names, but proper formatting helps prevent issues.

Tool Lifecycle

Creating Agent with Tools

POST /v1/agents
{
  "agent_type": "voice",
  "agent_name": "Support Bot",
  "prompt": "You are a helpful support assistant...",
  "voice_id": "11labs-Adrian",
  "language": "en-US",
  "general_tools": [
    {"type": "end_call", "name": "end_call", "description": "End the call"}
  ]
}

Updating Tools

PATCH /v1/agents/{agent_id}/tools
{
  "tools": [
    {"type": "end_call", ...},
    {"type": "transfer_call", ...}  ← Added new tool
  ]
}

Getting Tools

GET /v1/agents/{agent_id}
→ Returns agent with "current_tools" array

Limitations & Notes

Important Limitations:

Voice agents only - SMS agents don’t support tools
Cal.com tools - Require Cal.com account and API key
Send SMS tool - Only works for numbers with SMS capability
Custom API tools - Your API must be publicly accessible or allow-list Teli IPs
Tool count - No hard limit, but keeping under 10 tools per agent improves AI performance

Performance Tips:

Fewer tools = Better AI performance - Only add tools you actually need
Clear descriptions - Help AI understand when to use each tool
Tool order doesn’t matter - AI selects appropriate tool based on conversation
Test thoroughly - Test each tool in various conversation scenarios

Advanced Features

Warm Transfer Options

Warm transfers support additional configuration:

{
  "type": "transfer_call",
  "name": "transfer_with_context",
  "description": "Transfer to sales with customer context",
  "transfer_destination": {
    "type": "predefined",
    "number": "+15551234567"
  },
  "transfer_option": {
    "type": "warm_transfer",
    "on_hold_music": "uplifting_beats",
    "show_transferee_as_caller": true,
    "agent_detection_timeout_ms": 30000
  }
}

on_hold_music

string

Music while caller is on hold:

"none" - No music
"relaxing_sound" - Calm background music
"uplifting_beats" - Energetic music
"ringtone" - Standard ringtone

show_transferee_as_caller

boolean

If true, shows caller’s number to transfer destination (requires telephony support)

agent_detection_timeout_ms

number

Maximum time to wait for human detection (default: 30000ms)

Custom API Advanced

{
  "type": "custom",
  "name": "process_payment",
  "description": "Process customer payment",
  "url": "https://api.yourpayments.com/charge",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "query_params": {
    "currency": "USD"
  },
  "response_variables": {
    "transaction_id": "data.transaction.id",
    "receipt_url": "data.receipt_url"
  },
  "speak_during_execution": true,
  "speak_after_execution": true,
  "execution_message_description": "Say: Processing your payment now, one moment please",
  "timeout_ms": 10000
}

response_variables

object

Extract values from API response as dynamic variables for later use. Key: variable name, Value: JSON path in response

speak_during_execution

boolean

Whether AI speaks while API call is in progress

execution_message_description

string

What AI should say during execution (only if speak_during_execution: true)

timeout_ms

number

API call timeout in milliseconds (1000-600000, default: 120000)

Testing Tools

Test in Sandbox

Create test agent with tools
Make test calls
Trigger each tool
Verify behavior
Check logs for tool execution

Monitor Tool Usage

View call logs to see which tools were triggered
Check call analysis for tool execution details
Review conversation transcripts for context

Troubleshooting

Tool Not Triggering

Problem: AI doesn’t use the tool during calls Solutions:

Improve description - Be specific about when to use
Update prompt - Explicitly mention tool in agent prompt
Reduce tool count - Too many tools confuses AI
Test prompt - Include example scenario

API Tool Errors

Problem: Custom API tool returns errors Solutions:

Verify URL - Check API endpoint is correct
Check headers - Ensure authorization is valid
Test endpoint - Call API directly to verify
Check timeout - Increase timeout_ms if needed

Transfer Fails

Problem: Call transfer doesn’t complete Solutions:

Verify number - Check E.164 format (+15551234567)
Check telephony - Ensure transfer is supported
Try cold transfer - If warm transfer fails
Check extension - Validate extension digits

Rate Limits

No specific rate limits on tool updates, but:

Avoid updating same agent tools repeatedly in quick succession
Batch your tool changes (update all at once)
Cache tool configurations client-side when possible

Create Agent - Create agent with initial tools
Get Agent - Retrieve agent with current tools
Update Agent - Update agent configuration
List Agents - List all agents

Support

Need help with tools?

Check our agent creation guide
View example implementations
Contact Teli support for advanced use cases

Ready to enhance your voice agents with powerful tools! 🚀

Getting Started

Organizations

Users

AI Agents

Knowledge Base

Contacts & Leads

SMS Campaigns

Voice Campaigns

Phone Numbers

Call History

Do Not Call (DNC)

10DLC SMS Registration

Reference

​Overview

​Authentication

​Path Parameters

​Request Body

​Supported Tool Types

​1. End Call

​2. Transfer Call

​3. Custom API Integration

​4. Check Calendar Availability (Cal.com)

​5. Book Appointment (Cal.com)

​6. Agent Transfer

​7. Send SMS

​8. Extract Dynamic Variables

​9. Press Digit (DTMF)

​10. MCP (Model Context Protocol)

​Request Examples

​Update with Single Tool

​Update with Multiple Tools

​Healthcare Appointment Example

​Sales Bot Example

​Response

​Success Response

​Error Responses

​Tool Naming Requirements

​Dynamic Variables

​Best Practices

​1. Tool Descriptions

​2. Tool Combinations

​3. Error Handling

​4. Tool Naming

​Common Use Cases

​Customer Support

​Healthcare

​Sales & Lead Qualification

​Appointment Scheduling

​Response Examples

​Successful Update

​Error: Not a Voice Agent

​Error: Agent Not Found

​Error: Invalid Tool Configuration

​Tool Lifecycle

​Creating Agent with Tools

​Updating Tools

​Getting Tools

​Limitations & Notes

​Advanced Features

​Warm Transfer Options

​Custom API Advanced

​Testing Tools

​Test in Sandbox

​Monitor Tool Usage

​Troubleshooting

​Tool Not Triggering

​API Tool Errors

​Transfer Fails

​Rate Limits

​Related Endpoints

​Support

Overview

Authentication

Path Parameters

Request Body

Supported Tool Types

1. End Call

2. Transfer Call

3. Custom API Integration

4. Check Calendar Availability (Cal.com)

5. Book Appointment (Cal.com)

6. Agent Transfer

7. Send SMS

8. Extract Dynamic Variables

9. Press Digit (DTMF)

10. MCP (Model Context Protocol)

Request Examples

Update with Single Tool

Update with Multiple Tools

Healthcare Appointment Example

Sales Bot Example

Response

Success Response

Error Responses

Tool Naming Requirements

Dynamic Variables

Best Practices

1. Tool Descriptions

2. Tool Combinations

3. Error Handling

4. Tool Naming

Common Use Cases

Customer Support

Healthcare

Sales & Lead Qualification

Appointment Scheduling

Response Examples

Successful Update

Error: Not a Voice Agent

Error: Agent Not Found

Error: Invalid Tool Configuration

Tool Lifecycle

Creating Agent with Tools

Updating Tools

Getting Tools

Limitations & Notes

Advanced Features

Warm Transfer Options

Custom API Advanced

Testing Tools

Test in Sandbox

Monitor Tool Usage

Troubleshooting

Tool Not Triggering

API Tool Errors

Transfer Fails

Rate Limits

Related Endpoints

Support