Skip to main content

​
What Is Function Calling?

Function calling lets your AI agent execute actions during a call. Instead of just talking, your agent can:
  • Book appointments in your calendar
  • Look up orders in your database
  • Update CRM records
  • Process payments
  • End the call gracefully when the conversation is complete

Real-Time Integration

Connect your AI to your existing systems. No need to rebuild your infrastructure.

Natural Experience

Users don’t know the AI is calling APIs. It feels like talking to a human agent.

Flexible

Define functions with any parameters. Works with REST APIs, GraphQL, databases, and more.

Secure

Functions run on your servers with your credentials. TopCalls never stores your API keys.

​
How It Works

1

1. Configure Tools

Define the tools your AI agent can use when setting up a call or campaign through the TopCalls dashboard, or include them in your API call configuration.
2

2. AI Decides

During the conversation, the AI decides when to call a tool based on the user’s request.
3

3. Tool Execution

TopCalls sends a webhook to your server with the tool name and parameters. Your server executes the function.
4

4. Response

Your server returns the result. The AI uses this information to continue the conversation naturally.

​
Built-in Tools

TopCalls provides built-in tools that are automatically available during calls.

​
end_call

The end_call tool allows your AI agent to gracefully end the call when the conversation is complete.
The AI uses end_call automatically when appropriate. The agent decides when to end based on context: user says goodbye, all questions answered, or clear conversation conclusion.
When the AI uses end_call:
  • User says “goodbye”, “thanks, that’s all”, etc.
  • All questions have been answered
  • User explicitly asks to end the call
  • Conversation naturally concludes
What happens:
  1. AI decides to end the call
  2. AI speaks a contextual farewell message
  3. Call is terminated
You can influence end-call behavior in your instructions: “Always confirm the next steps before ending the call” or “Offer to help with anything else before saying goodbye.”

​
Custom Tools

Define custom tools to connect your AI agent to your systems. When the AI invokes a tool, TopCalls sends a webhook to your server.

​
Tool Definition Example

{
  "name": "check_availability",
  "description": "Check if a time slot is available for appointments",
  "parameters": {
    "date": {
      "type": "string",
      "description": "The date to check (YYYY-MM-DD)"
    },
    "time": {
      "type": "string",
      "description": "The time to check (HH:MM format)"
    }
  }
}

​
Handling Tool Calls

When the AI wants to call a tool, TopCalls sends a webhook to your server: 
{
  "event": "tool.call",
  "call_id": "564d4fd4-03bc-400a-abe0-05540fbeff88",
  "tool_name": "check_availability",
  "parameters": {
    "date": "2025-12-24",
    "time": "15:00"
  }
}

​
Your Server Response

Return the result as JSON: 
{
  "result": {
    "available": true,
    "slots": ["09:00", "10:00", "11:00", "14:00", "15:00"]
  }
}
The AI uses this to continue the conversation:
“I checked availability and we have slots at 9 AM, 10 AM, 11 AM, 2 PM, and 3 PM. Which works best for you?”

​
Real-World Examples

​
Order Lookup

{
  "name": "lookup_order",
  "description": "Look up an order by order number and return its status",
  "parameters": {
    "order_number": {
      "type": "string",
      "description": "The order number to look up"
    }
  }
}

​
CRM Update

{
  "name": "update_lead_status",
  "description": "Update a lead's status in the CRM",
  "parameters": {
    "lead_id": {
      "type": "string",
      "description": "The lead ID"
    },
    "status": {
      "type": "string",
      "enum": ["interested", "not_interested", "demo_scheduled"],
      "description": "New status for the lead"
    },
    "notes": {
      "type": "string",
      "description": "Notes from the conversation"
    }
  }
}

​
Tool Execution Flow

User: "Can you check if 3 PM tomorrow is available?"

AI: [Decides to call check_availability tool]
    → TopCalls sends webhook to your server
    → Your server checks calendar
    → Your server returns: {"available": true}

AI: "Yes, 3 PM tomorrow is available! Would you like to book it?"

​
Error Handling

If a tool call fails, return an error: 
{
  "error": {
    "message": "Time slot is already booked",
    "code": "SLOT_UNAVAILABLE"
  }
}
The AI handles this gracefully:
“I’m sorry, that time slot is already booked. Let me check other available times…”

​
Best Practices

​
Do This

  • Clear descriptions: Write detailed tool descriptions so the AI knows when to use them
  • Validate parameters: Always validate parameters on your server
  • Return structured data: Use consistent response formats
  • Handle errors gracefully: Return clear error messages
  • Fast responses: Return results quickly (< 2 seconds) for natural conversation

​
Avoid This

  • Vague descriptions: “Helper function” doesn’t help the AI decide when to use it
  • Slow APIs: Don’t call slow external APIs synchronously
  • Ignore errors: Always handle errors and return appropriate responses
  • Too many tools: Limit to 5-10 tools per call for best results

​
Security Considerations

  • API Keys: Store API keys securely on your server, never in the call configuration
  • Validation: Always validate tool parameters before execution
  • Rate Limiting: Implement rate limiting on your tool endpoints
  • Authentication: Use webhook signatures to verify requests are from TopCalls
  • Authorization: Check permissions before executing tools

​
Next Steps

Making Calls

Learn how to include tools when making calls.

Webhooks

Set up webhooks to receive tool call requests.