Dynamic assistant configuration webhook
Called **BEFORE** an inbound call is answered, allowing you to: - Dynamically configure the assistant based on caller information - Personalize the greeting message - Override STT/LLM/TTS configuration - Set call-specific analysis plans - Reject calls based on business logic (e.g., outside business hours) - Pass custom metadata that will be echoed in all subsequent webhook events ⚠️ **Important:** Your endpoint must respond within **5 seconds** or the call will proceed with default agent configuration. ### Response Modes **1. Default mode** - Use saved agent config: ```json {} ``` **2. Transient agent** - Full config override: ```json { "assistant": { "first_message": "Hello John!", "tts_config": {"voice_id": "..."}, "metadata": {"crm_id": "12345"} } } ``` **3. Hybrid agent** - Reference saved agent + overrides: ```json { "assistant_id": "uuid-of-saved-agent", "assistant_override": { "tts_config": {"voice_id": "female-voice"}, "first_message": "Hello John!", "metadata": {"crm_id": "12345"} } } ``` The hybrid mode uses **shallow merge**: each top-level key in `assistant_override` completely replaces that config block from the saved agent. ### Custom Metadata Any fields you add to the assistant config (like `metadata`) will be echoed back in all subsequent webhook events (`status-update`, `tool-calls`, `end-of-call-report`). This is useful for passing CRM IDs, campaign info, or any context you need.
Called BEFORE an inbound call is answered, allowing you to:
- Dynamically configure the assistant based on caller information
- Personalize the greeting message
- Override STT/LLM/TTS configuration
- Set call-specific analysis plans
- Reject calls based on business logic (e.g., outside business hours)
- Pass custom metadata that will be echoed in all subsequent webhook events
⚠️ Important: Your endpoint must respond within 5 seconds or the call will proceed with default agent configuration.
Response Modes
1. Default mode - Use saved agent config:
{}2. Transient agent - Full config override:
{
"assistant": {
"first_message": "Hello John!",
"tts_config": {"voice_id": "..."},
"metadata": {"crm_id": "12345"}
}
}3. Hybrid agent - Reference saved agent + overrides:
{
"assistant_id": "uuid-of-saved-agent",
"assistant_override": {
"tts_config": {"voice_id": "female-voice"},
"first_message": "Hello John!",
"metadata": {"crm_id": "12345"}
}
}The hybrid mode uses shallow merge: each top-level key in assistant_override completely replaces that config block from the saved agent.
Custom Metadata
Any fields you add to the assistant config (like metadata) will be echoed back in all subsequent webhook events (status-update, tool-calls, end-of-call-report). This is useful for passing CRM IDs, campaign info, or any context you need.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
Example Requests
Payload sent to assistant-request webhook before call is answered
/assistant-requestHealth check GET
Returns the current health status of the API and its dependencies. No authentication required.
Tool/Function Call Webhook
Called when the AI needs to execute a tool/function during the conversation. **Sync tools:** Must respond within **10 seconds** with the result. **Async tools:** Respond immediately with `200 OK` (fire-and-forget). Tools are defined in `llm_config.tools[]` with optional per-tool URL override. ### Assistant Object The payload includes the full `assistant` object containing: - All resolved configuration (after any overrides from `assistant-request`) - Any custom `metadata` you passed in the `assistant-request` response ### Response Formats Multiple response formats are supported: 1. **Object format** (recommended): ```json {"results": [{"tool_call_id": "tool_abc123", "result": {"name": "Jan"}}]} ``` 2. **Simple format**: ```json {"result": {"name": "Jan"}} ``` 3. **Direct format** (your data directly): ```json {"name": "Jan"} ``` 4. **Error format**: ```json {"error": "Contact not found"} ```