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
  • Check inventory
  • End the call gracefully when the conversation is complete
  • And anything else your API can do

Real-Time Integration

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

Seamless Experience

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

Flexible

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

Secure

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

​
How It Works

1

1. Define Tools

When creating a call, provide tool definitions with names, descriptions, and parameters.
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 calls your webhook 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. You don’t need to define these—they’re ready to use.

​
end_call

The end_call tool allows your AI agent to gracefully end the call when the conversation is complete.
The AI will automatically use end_call when appropriate—you don’t need to configure anything. 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 (e.g., “Thanks for calling! Your appointment is confirmed. Have a great day!”)
  3. Call is terminated
Example behavior: 
User: "Great, that's everything I needed. Thanks!"

AI: [Invokes end_call with farewell message]
    "You're welcome! I've confirmed your appointment for tomorrow 
    at 3 PM. Have a wonderful day!"
    
[Call ends]
You can influence the AI’s 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.”

​
book_appointment

Automatically available for appointment scheduling. Updates the call record with the booked slot.

​
Defining Custom Tools

​
Basic Tool Definition

{
  "tools": [
    {
      "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)"
        }
      }
    }
  ]
}

​
Complete Example: Appointment Booking

{
  "phone_number": "+14155551234",
  "instructions": "You are Sarah, an appointment coordinator. Help users book or reschedule appointments.",
  "tools": [
    {
      "name": "check_availability",
      "description": "Check available appointment slots for a given date",
      "parameters": {
        "date": {
          "type": "string",
          "description": "Date to check (YYYY-MM-DD)"
        }
      }
    },
    {
      "name": "book_appointment",
      "description": "Book an appointment for a patient",
      "parameters": {
        "patient_id": {
          "type": "string",
          "description": "Patient ID"
        },
        "date": {
          "type": "string",
          "description": "Appointment date (YYYY-MM-DD)"
        },
        "time": {
          "type": "string",
          "description": "Appointment time (HH:MM)"
        }
      }
    }
  ],
  "webhook_url": "https://your-app.com/webhooks/call"
}

​
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

Your server should return the result: 
{
  "result": {
    "available": true,
    "slots": [
      "09:00", "10:00", "11:00", "14:00", "15:00"
    ]
  }
}
The AI uses this information to continue the conversation:
“Great! 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

​
Example 1: 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"
    }
  }
}
Webhook payload: 
{
  "tool_name": "lookup_order",
  "parameters": {
    "order_number": "ORD-12345"
  }
}
Your response: 
{
  "result": {
    "status": "shipped",
    "tracking_number": "1Z999AA10123456784",
    "estimated_delivery": "2025-12-26"
  }
}

​
Example 2: 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": "Additional notes from the conversation"
    }
  }
}

​
Example 3: Payment Processing

{
  "name": "process_payment",
  "description": "Process a payment for an invoice",
  "parameters": {
    "invoice_id": {
      "type": "string",
      "description": "Invoice ID"
    },
    "amount": {
      "type": "number",
      "description": "Payment amount"
    },
    "payment_method": {
      "type": "string",
      "enum": ["credit_card", "bank_transfer"],
      "description": "Payment method"
    }
  }
}

​
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 will handle 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
  • Log everything: Keep logs of all tool calls for debugging
  • Fast responses: Return results quickly (< 2 seconds) for natural conversation

​
❌ Don’t Do This

  • Vague descriptions: “Helper function” doesn’t help the AI
  • Slow APIs: Don’t call slow external APIs synchronously
  • Ignore errors: Always handle errors and return appropriate responses
  • Complex parameters: Keep parameter schemas simple
  • 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.