Function Calling

HostDesk supports function calling (tool use) during voice conversations. When the LLM decides to call a function, HostDesk sends a webhook to your server and streams the result back into the conversation.

How it works

1. Define tools in your assistant's config or worker setup
2. During a call, the LLM generates a function call
3. HostDesk sends a POST request to your webhook_url with the function name and arguments
4. Your server processes the request and returns a result
5. The result is fed back to the LLM, which continues the conversation

Webhook format

HostDesk sends a POST request with:

{
  "type": "function_call",
  "function": {
    "name": "check_order_status",
    "arguments": {
      "order_id": "ORD-12345"
    }
  },
  "call_id": "room-name",
  "assistant_id": "asst-uuid"
}

Your server should respond with:

{
  "result": "Order ORD-12345 is shipped and arriving tomorrow."
}

Using FunctionHandler (Python SDK)

The SDK provides FunctionHandler for easy webhook handling:

from echoai import FunctionHandler

handler = FunctionHandler()

@handler.register("check_order_status")
def check_order(order_id: str) -> str:
    # Look up order in your database
    return f"Order {order_id} is shipped."

@handler.register("get_weather")
def get_weather(city: str) -> str:
    return f"72°F and sunny in {city}."

Flask / FastAPI integration

Use create_function_webhook_app to create a ready-to-use webhook server:

from echoai import FunctionHandler, create_function_webhook_app

handler = FunctionHandler()

@handler.register("check_order_status")
def check_order(order_id: str) -> str:
    return "Order shipped."

# Creates a Flask app that handles POST /webhook
app = create_function_webhook_app(handler, webhook_secret="whsec_abc123")

Run it:

pip install flask
python -c "from your_module import app; app.run(port=5000)"

Verifying webhook signatures

All function call webhooks are signed with HMAC-SHA256. See Webhook Signatures for verification details.

Defining tools for the LLM

Tools are defined as JSON schemas that the LLM uses to decide when and how to call functions:

tools = [
    {
        "type": "function",
        "function": {
            "name": "check_order_status",
            "description": "Check the status of a customer order",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "The order ID"
                    }
                },
                "required": ["order_id"]
            }
        }
    }
]

Store these in your assistant's provider_config or define them in your worker code.