Skip to main content

​
Function Definition Structure

A complete function definition includes: 
{
  "name": "function_name",
  "description": "Clear description of what this function does and when to use it",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  },
  "api_endpoint": "https://api.yourcompany.com/endpoint",
  "http_method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body_template": {
    "field": "{{param1}}"
  }
}

​
Components

​
Name

  • Use snake_case
  • Be descriptive but concise
  • Unique within agent
{
  "name": "check_order_status"
}

​
Description

The most important part. Be specific about:
  • What the function does
  • When to call it
  • What triggers it
❌ Bad: 
{
  "description": "Gets data"
}
✅ Good: 
{
  "description": "Retrieves the customer's order status including tracking information and estimated delivery date. Call this when the customer asks about their order, delivery, shipping, or tracking."
}

​
Parameters

Define using JSON Schema: 
{
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order number or ID"
      },
      "email": {
        "type": "string",
        "format": "email",
        "description": "Customer's email for verification"
      }
    },
    "required": ["order_id"]
  }
}

​
API Endpoint

Your API URL to call: 
{
  "api_endpoint": "https://api.yourcompany.com/orders/status"
}

​
HTTP Method

{
  "http_method": "POST"
}
Options: GET, POST, PUT, PATCH, DELETE

​
Headers

Authentication and content type: 
{
  "headers": {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json",
    "X-Custom-Header": "value"
  }
}

​
Body Template

Map parameters to API request body: 
{
  "body_template": {
    "order_id": "{{order_id}}",
    "customer_email": "{{email}}",
    "source": "ai_agent"
  }
}

​
Context Variables

Use these built-in variables:
VariableDescription
{{agent_id}}Current agent ID
{{call_sid}}Unique call ID
{{from_number}}Caller’s phone number
{{to_number}}Called phone number
{{contact_id}}Contact ID (if available)
{{contact_name}}Contact name
Plus any custom variables from contact metadata.

​
Parameter Types

​
String

{
  "name": {
    "type": "string",
    "description": "Customer's full name"
  }
}

​
Number

{
  "quantity": {
    "type": "number",
    "minimum": 1,
    "maximum": 100,
    "description": "Quantity to order"
  }
}

​
Boolean

{
  "send_confirmation": {
    "type": "boolean",
    "description": "Whether to send email confirmation"
  }
}

​
Enum

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"],
    "description": "Priority level"
  }
}

​
Array

{
  "items": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "List of items"
  }
}

​
Object

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["street", "city"]
  }
}

​
HTTP Methods

​
GET

Retrieve data without side effects: 
{
  "http_method": "GET",
  "api_endpoint": "https://api.yourcompany.com/customers/{{customer_id}}",
  "query_params": {
    "include": "orders,profile"
  }
}

​
POST

Create new resources or submit data: 
{
  "http_method": "POST",
  "api_endpoint": "https://api.yourcompany.com/orders",
  "body_template": {
    "customer_id": "{{customer_id}}",
    "items": "{{items}}"
  }
}

​
PUT

Update existing resources: 
{
  "http_method": "PUT",
  "api_endpoint": "https://api.yourcompany.com/customers/{{customer_id}}",
  "body_template": {
    "phone": "{{phone_number}}",
    "email": "{{email}}"
  }
}

​
Authentication

​
Bearer Token

{
  "headers": {
    "Authorization": "Bearer {{API_KEY}}"
  }
}

​
API Key Header

{
  "headers": {
    "X-API-Key": "{{API_KEY}}"
  }
}

​
Basic Auth

{
  "headers": {
    "Authorization": "Basic {{BASE64_CREDENTIALS}}"
  }
}
Never hardcode API keys. Use environment variables: {{API_KEY}}.

​
Next Steps

Examples

View ready-to-use function examples

Best Practices

Learn function calling best practices