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
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:
Variable Description {{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}}" } }
{ "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
