VoiceDock Docs
ApiWebhooks

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

POST/assistant-request