# VoiceDock Documentation

> VoiceDock is a voice AI platform. Build AI voice assistants that handle phone calls, run custom functions, and integrate with your stack. The full page contents are available at /llms-full.txt.

## Pages

- [Changelog](https://doc.voicedock.ai/docs/changelog): Notable changes to the VoiceDock platform, API, and documentation.
- [Introduction](https://doc.voicedock.ai/docs/introduction): VoiceDock is a voice AI platform powered by HMS Sovereign v1. Build AI voice assistants that handle phone calls, run custom functions, and integrate with your stack.
- [Analysis Templates](https://doc.voicedock.ai/docs/configuration/analysis-templates): Define reusable configurations for post-call analysis and reference them across multiple assistants.
- [Custom Tools](https://doc.voicedock.ai/docs/configuration/custom-tools): Allow your AI assistant to execute functions during calls, like looking up customer information or booking appointments.
- [SIP Trunks](https://doc.voicedock.ai/docs/configuration/sip-trunks): Configure SIP trunks to enable call transfers from your AI assistant to external phone systems.
- [Tool Templates](https://doc.voicedock.ai/docs/configuration/tool-templates): Define reusable tool configurations that can be easily added to multiple assistants.
- [Assistants](https://doc.voicedock.ai/docs/core-concepts/assistants): Assistants are AI-powered voice entities that handle phone conversations, each with its own personality, knowledge, and capabilities.
- [Calls](https://doc.voicedock.ai/docs/core-concepts/calls): Calls represent phone conversations handled by your AI assistants. HMS Sovereign supports both inbound and outbound calls.
- [Phone Numbers](https://doc.voicedock.ai/docs/core-concepts/phone-numbers): Phone numbers are the entry point for your AI assistants. Incoming calls to registered numbers are handled by the assigned assistant.
- [Webhooks](https://doc.voicedock.ai/docs/core-concepts/webhooks): Webhooks allow you to receive real-time notifications about call events via HTTP POST requests to your configured endpoint.
- [AI Generation](https://doc.voicedock.ai/docs/features/ai-generation): AI-powered generation tools that help you configure voice assistants faster by turning natural-language descriptions into production-ready configurations.
- [Autonomous Silence Handling](https://doc.voicedock.ai/docs/features/autonomous-silence-handling): Intelligently detect and respond to prolonged silence during calls, preventing calls from hanging indefinitely.
- [Call Analysis](https://doc.voicedock.ai/docs/features/call-analysis): Extract structured data from call transcripts using AI to automatically capture sentiment, intents, and outcomes.
- [Call Transfers](https://doc.voicedock.ai/docs/features/call-transfers): Transfer calls from your AI assistant to human agents, other departments, or external numbers using SIP trunks or the built-in transfer tool.
- [Campaigns Setup](https://doc.voicedock.ai/docs/features/campaigns-setup): Technical setup guide for deploying the outbound campaigns infrastructure with Edge Functions and database triggers.
- [Outbound Campaigns](https://doc.voicedock.ai/docs/features/campaigns): Set up automated outbound calling campaigns to reach leads with personalized AI conversations.
- [Privacy & Compliance](https://doc.voicedock.ai/docs/features/privacy-compliance): HMS Sovereign provides Recording Consent (DTMF opt-in) and GDPR Mode for privacy-conscious deployments.
- [Voicemail Detection](https://doc.voicedock.ai/docs/features/voicemail-detection): Detect voicemail systems on outbound calls and optionally leave a pre-configured message.
- [Web Calls](https://doc.voicedock.ai/docs/features/web-calls): Let users speak directly to an AI assistant from their browser via WebRTC, no phone number required.
- [Workflow definitions](https://doc.voicedock.ai/docs/features/workflow-definitions): The workflow definition contract (v1): every field of nodes and edges, the validation rules, and a complete working example.
- [Workflows](https://doc.voicedock.ai/docs/features/workflows): Build multi-step call flows on a visual canvas: conversation steps, background tool calls, human transfers and clean endings — with one assistant supplying the voice and call settings.
- [Authentication](https://doc.voicedock.ai/docs/get-started/authentication): All API requests require authentication using a Bearer token in the Authorization header.
- [Quickstart](https://doc.voicedock.ai/docs/get-started/quickstart): Create your first AI voice assistant and make it available on a phone number in minutes.
- [Data Processing Agreement](https://doc.voicedock.ai/docs/guides/data-processing-agreement): VoiceDock standard DPA compliant with GDPR Article 28, covering the Vertex-EU plus GDPR-mode configuration.
- [BYOK Setup](https://doc.voicedock.ai/docs/integrations/byok-setup): Bring Your Own Key allows you to use your own API keys for AI providers, giving you control over costs and model access.
- [MCP Server](https://doc.voicedock.ai/docs/integrations/mcp-server): Connect AI coding assistants like Claude Code and Cursor to your VoiceDock account via the hosted Model Context Protocol server — just sign in, no API key to paste.
- [Provider Pricing](https://doc.voicedock.ai/docs/integrations/provider-pricing): Reference pricing for STT, LLM, and TTS providers used with HMS Sovereign.
- [xAI Grok Integration](https://doc.voicedock.ai/docs/integrations/xai-grok-integration): Use xAI Grok Realtime API for speech-to-speech conversation with sub-700ms latency.
- [Error Codes](https://doc.voicedock.ai/docs/reference/error-codes): Complete reference of all error codes returned by the HMS Sovereign API with explanations and recommended actions.
- [Rate Limits](https://doc.voicedock.ai/docs/reference/rate-limits): API rate limits, response headers, and best practices for staying within limits.
- [Troubleshooting](https://doc.voicedock.ai/docs/reference/troubleshooting): Common issues when integrating with HMS Sovereign and how to resolve them.
- [Node.js SDK](https://doc.voicedock.ai/docs/sdks/node): Official TypeScript/Node.js SDK for the HMS Sovereign Voice AI Platform with zero dependencies and full type safety.
- [Build a voice agent](https://doc.voicedock.ai/docs/tutorials/build-a-voice-agent): Configure an assistant from scratch in the VoiceDock dashboard, then place a live test call.
- [Billing & Credits](https://doc.voicedock.ai/docs/platform/billing): HMS Sovereign uses a credits-based billing system where you purchase credits upfront and consume them as you make and receive calls.
- [Dashboard Security](https://doc.voicedock.ai/docs/platform/dashboard-security): Authentication model, access controls, and security measures for all HMS Sovereign dashboard users.
- [EU Data Sovereignty](https://doc.voicedock.ai/docs/platform/eu-data-sovereignty): EU-hosted voice AI with strong data residency guarantees, processing and storing data exclusively within the European Union.
- [Privacy Policy](https://doc.voicedock.ai/docs/platform/privacy-policy): How Flireo B.V. collects, processes, and protects personal data in connection with the HMS Sovereign Voice AI Platform.
- [Voice Selection Psychology](https://doc.voicedock.ai/docs/platform/voice-selection-psychology): How voice selection impacts caller behavior and why slightly robotic voices can outperform natural voices in transactional use cases.
- [Whitelabel](https://doc.voicedock.ai/docs/platform/whitelabel): Build your own branded AI calling business with custom portals where clients sign up, purchase credits, and make AI calls under your brand.
- [Assistant Request Webhook](https://doc.voicedock.ai/docs/webhooks/assistant-request): Called before an inbound call is answered, allowing dynamic assistant configuration based on caller information.
- [End of Call Report Webhook](https://doc.voicedock.ai/docs/webhooks/end-of-call-report): Called after a call ends with a summary and optional structured analysis for CRM integrations.
- [Webhooks Overview](https://doc.voicedock.ai/docs/webhooks/overview): Receive real-time notifications about call events via HTTP POST requests to your configured endpoint.
- [Webhook Security](https://doc.voicedock.ai/docs/webhooks/security): Verify HMAC-SHA256 webhook signatures to ensure requests come from HMS Sovereign.
- [Status Update Webhook](https://doc.voicedock.ai/docs/webhooks/status-update): Called when the call status changes to track the call lifecycle in your systems.
- [Tool Calls Webhook](https://doc.voicedock.ai/docs/webhooks/tool-calls): Called when the AI assistant needs to execute a custom tool or function during a conversation.
- [List all assistants](https://doc.voicedock.ai/docs/api/assistants/listAssistants): Retrieve all AI voice assistants in your organization.
- [Create a new assistant](https://doc.voicedock.ai/docs/api/assistants/createAssistant): Create a new AI voice assistant with custom STT, LLM, and TTS configurations. Only the name is required - defaults will be applied for other settings.
- [Get an assistant](https://doc.voicedock.ai/docs/api/assistants/getAssistant): Retrieve a specific assistant by ID.
- [Update an assistant](https://doc.voicedock.ai/docs/api/assistants/updateAssistant): Update an existing assistant. Only provided fields will be updated.
- [Delete an assistant](https://doc.voicedock.ai/docs/api/assistants/deleteAssistant): Delete an assistant. Any phone numbers assigned to this assistant will have their assistant_id set to null.
- [List all phone numbers](https://doc.voicedock.ai/docs/api/numbers/listNumbers): Retrieve all phone numbers in your organization with their assigned agents, transfer trunks and workflows.
- [Register a phone number](https://doc.voicedock.ai/docs/api/numbers/createNumber): Register a new phone number in your organization. The number must be configured with your SIP provider to forward calls to HMS Sovereign.
- [Get a phone number](https://doc.voicedock.ai/docs/api/numbers/getNumber): Retrieve a specific phone number by ID.
- [Update a phone number](https://doc.voicedock.ai/docs/api/numbers/updateNumber): Update the agent assignment, transfer trunk or attached workflow for a phone number.
- [Delete a phone number](https://doc.voicedock.ai/docs/api/numbers/deleteNumber): Remove a phone number from your organization.
- [List all workflows](https://doc.voicedock.ai/docs/api/workflows/listWorkflows): Retrieve all workflows in your organization. The list view summarizes each graph (entry node, node and edge counts); request a single workflow to get the full definition.
- [Create a workflow](https://doc.voicedock.ai/docs/api/workflows/createWorkflow): Create a workflow. The definition is validated on write: invalid definitions are rejected with HTTP 400 and a `details` array listing every problem (unknown node references, unreachable nodes, missing edge descriptions, and so on), so a workflow that saves is a workflow that runs. Attach it to a phone number with `PATCH /numbers/{id}`.
- [Get a workflow](https://doc.voicedock.ai/docs/api/workflows/getWorkflow): Retrieve a specific workflow with its full definition.
- [Update a workflow](https://doc.voicedock.ai/docs/api/workflows/updateWorkflow): Update a workflow's name, definition or active state. A new definition replaces the old one entirely and is validated the same way as on create. Changes apply to the next call; calls already in progress finish on the definition they started with.
- [Delete a workflow](https://doc.voicedock.ai/docs/api/workflows/deleteWorkflow): Delete a workflow. Deletion is refused with HTTP 409 while phone numbers still run this workflow - detach them first with `PATCH /numbers/{id}` and `workflow_id: null` - so live numbers never change behaviour as a side effect.
- [List calls](https://doc.voicedock.ai/docs/api/calls/listCalls): Retrieve call history with optional filtering by status and date range. Returns complete call data including transcripts, analysis results, and metadata.
- [Get call by ID](https://doc.voicedock.ai/docs/api/calls/getCall): Retrieve complete details for a specific call including transcript, analysis results, and all metadata.
- [Initiate outbound call](https://doc.voicedock.ai/docs/api/calls/createOutboundCall): Initiate an outbound call from an AI assistant to a destination phone number.

**Phone Number Selection (Important for Resellers):**

You can specify which phone number to call from using the `number_id` parameter. This is **highly recommended** for:
- **Resellers**: Ensure calls are made from numbers dedicated to specific clients
- **Branding**: Always use the same caller ID for recognition
- **Compliance**: Meet legal requirements for specific numbers
- **Local presence**: Use local numbers for better answer rates

If `number_id` is not provided, the system will automatically select an available number from your organization's pool, which may not be appropriate for reseller scenarios where numbers are client-specific.

**Three Usage Modes:**

1. **Reference Mode** (`assistant_id`)
   - Reference an existing assistant from your dashboard
   - Uses the assistant's pre-configured settings
   - Simplest option for standard calls

2. **Transient Mode** (`assistant`)
   - Create a one-time assistant configuration without saving
   - Full control over STT/LLM/TTS configuration
   - Perfect for personalized or context-specific calls

3. **Hybrid Mode** (`assistant_id` + `assistant_override`)
   - Reference a saved assistant as the base
   - Override specific fields (e.g., first_message, llm_config.messages)
   - Best for personalization while keeping base config

**⚠️ Deprecated:** `agent_id`, `agent`, and `agent_config` are deprecated. Use `assistant_id`, `assistant`, and `assistant_override` instead.

**Use Cases:**
- Appointment reminders with personalized greetings
- Customer follow-ups with dynamic context
- Survey calls with specific question flows
- Delivery notifications
- Payment reminders with account-specific details

**Configuration Notes:**
- When using `xai_realtime` provider, omit `stt_config` and `tts_config` (handled internally)
- For other providers (`openai`, `mistral`), both `stt_config` and `tts_config` are required
- The call will be initiated immediately and the response will include a `call_id` to track progress

**Response Time:** Your call will typically connect within 2-5 seconds.
- [Send control command to active call](https://doc.voicedock.ai/docs/api/call-control/controlCall): Send real-time commands to an active call. The call must be in "in-progress" status.

**⚠️ IMPORTANT: xAI Realtime Model Limitations**

Call control has **significant limitations** when using xAI Realtime (grok-realtime-v1) due to its speech-to-speech architecture:

- ❌ `inject-context`: Limited effectiveness - context may not influence responses reliably
- ❌ `say`: Does not work reliably - commands often timeout or fail to trigger speech
- ✅ `end-call`: Works reliably
- ⚠️ `transfer`: Partial support - announcement may not work, but transfer executes

**Why the limitations?**
xAI Realtime is an end-to-end audio model that processes speech directly without intermediate text. It expects continuous audio input and cannot reliably respond to text-based control commands mid-conversation.

**Recommendation:**
If you need full call control support (`inject-context`, `say`, `transfer` with announcements), use the traditional pipeline:
- **Provider**: `openai` with `gpt-4o` or `gpt-4o-mini`
- **STT**: Deepgram (`nova-3-general`)
- **TTS**: ElevenLabs or OpenAI TTS
- **Result**: All control commands work reliably

**Command Types:**
- `inject-context`: Silently add information to the agent's context (traditional models only)
- `say`: Make the agent speak specific text (traditional models only)
- `end-call`: End the call with an optional final message (works with all models)
- `transfer`: Transfer the call to another destination (partial xAI Realtime support)

**Use Cases:**
- SMS verification: Inject received codes into the conversation
- CRM integration: Add customer context mid-call
- Human escalation: Transfer to a live agent
- Emergency end: Gracefully terminate problematic calls
- [List all campaigns](https://doc.voicedock.ai/docs/api/campaigns/listCampaigns): Retrieve all outbound campaigns in your organization.
- [Create a campaign](https://doc.voicedock.ai/docs/api/campaigns/createCampaign): Create a new outbound calling campaign with leads and schedule.
- [Get a campaign](https://doc.voicedock.ai/docs/api/campaigns/getCampaign): Retrieve a specific campaign by ID.
- [Update a campaign](https://doc.voicedock.ai/docs/api/campaigns/updateCampaign): Update campaign settings or status. Set status to `scheduled` to start calling.
- [Delete a campaign](https://doc.voicedock.ai/docs/api/campaigns/deleteCampaign): Delete a campaign and all its leads.
- [List campaign leads](https://doc.voicedock.ai/docs/api/campaigns/listCampaignLeads): Retrieve all leads in a campaign.
- [Add a lead](https://doc.voicedock.ai/docs/api/campaigns/addCampaignLead): Add a new lead to a campaign.
- [Remove a lead](https://doc.voicedock.ai/docs/api/campaigns/removeCampaignLead): Remove a lead from a campaign.
- [List chat messages](https://doc.voicedock.ai/docs/api/chats/listChatMessages): List chat messages for a contact, newest first. Use this for dashboards or manual inspection; use `/chats/context` when feeding history to an LLM or voice agent.
- [Append a chat message](https://doc.voicedock.ai/docs/api/chats/createChatMessage): Store a single chat message for a contact.

Chats are a lightweight, developer-first storage primitive. VoiceDock keeps the
messages — your application keeps the LLM logic, tools, and channel wiring
(Meta Cloud API, widget, SMS gateway, etc.). Pair with `GET /chats/context`
to share history between chat channels and voice agents.

Messages are append-only; update by inserting a new message and delete
individually via `DELETE /chats/{id}`.
- [Delete a chat message](https://doc.voicedock.ai/docs/api/chats/deleteChatMessage): Permanently delete a single chat message. Scoped to your organization.
- [Get conversation context for a contact](https://doc.voicedock.ai/docs/api/chats/getChatContext): Return the last N messages for a contact in chronological order (oldest → newest).

The response contains two views:
- `messages`: raw message rows ready to map into an LLM chat array.
- `formatted`: a single string (`ROLE: content` per line) convenient to append to a voice agent's system prompt for cross-channel continuity.
- [List all tool templates](https://doc.voicedock.ai/docs/api/tool-templates/listToolTemplates): Retrieve all tool templates in your organization.
- [Create a new tool template](https://doc.voicedock.ai/docs/api/tool-templates/createToolTemplate): Create a new reusable tool template. Tools can be of type 'function' (custom webhook), 'endCall' (built-in), or 'transferCall' (built-in).
- [Get a tool template](https://doc.voicedock.ai/docs/api/tool-templates/getToolTemplate): Retrieve a specific tool template by ID.
- [Update a tool template](https://doc.voicedock.ai/docs/api/tool-templates/updateToolTemplate): Update an existing tool template. Only provided fields will be updated.
- [Delete a tool template](https://doc.voicedock.ai/docs/api/tool-templates/deleteToolTemplate): Delete a tool template. Note that agents using this tool will continue to work as tools are stored as objects in the agent configuration, not as references.
- [List analysis templates](https://doc.voicedock.ai/docs/api/analysis-templates/listAnalysisTemplates): Get all analysis templates for your organization
- [Create analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/createAnalysisTemplate): Create a new analysis template for your organization
- [Get analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/getAnalysisTemplate): Retrieve a specific analysis template by ID
- [Update analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/updateAnalysisTemplate): Update an existing analysis template
- [Delete analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/deleteAnalysisTemplate): Delete an analysis template
- [List SIP trunks](https://doc.voicedock.ai/docs/api/sip-trunks/listSipTrunks): Retrieve all SIP trunks configured for your organization's call transfers.
- [Create a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/createSipTrunk): Create a new SIP trunk for call transfers. Passwords are stored securely in Vault.
- [Get a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/getSipTrunk): Retrieve a specific SIP trunk by ID.
- [Delete a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/deleteSipTrunk): Delete a SIP trunk. Any numbers using this trunk for transfers will have their transfer_trunk_id set to null.
- [Get BYOK configurations](https://doc.voicedock.ai/docs/api/byok/getBYOKConfigs): Retrieve all Bring Your Own Key configurations for your organization.
- [Add BYOK configuration](https://doc.voicedock.ai/docs/api/byok/addBYOKConfig): Add or update a Bring Your Own Key configuration. The API key is securely stored in Supabase Vault and only the vault secret ID is stored in the database.
- [Delete BYOK configuration](https://doc.voicedock.ai/docs/api/byok/deleteBYOKConfig): Remove a Bring Your Own Key configuration. This will delete the secret from Vault and remove the reference from the database.
- [Get BYOK provider configurations](https://doc.voicedock.ai/docs/api/byok/getBYOKProviderConfig): Retrieve available BYOK providers and their supported models
- [List available voices](https://doc.voicedock.ai/docs/api/voices/listVoices): Returns available voices for your agents.

## Voice Providers

### Local Voices (All Users)
Local voices are lightweight, fast, and cost-effective. They provide clear, slightly robotic speech that works well for transactional calls like appointments, surveys, and customer service.

This endpoint returns all available local voices grouped by language. Over 90 voices across 35+ languages are available.

### ElevenLabs (BYOK)
This endpoint does NOT return ElevenLabs voices. Check your ElevenLabs Voice Library at https://elevenlabs.io/app/voice-library for available voices when using your own API key.

**Available ElevenLabs models:** `eleven_flash_v2_5` (fastest, default), `eleven_v3` (expressive dialogue with audio tags - supports `[emotion]` cues in square brackets), `eleven_multilingual_v2` (best quality), `eleven_turbo_v2_5` (balanced), `eleven_monolingual_v1` (English only).

### xAI Grok Realtime (BYOK)
Grok Realtime has built-in voices (not returned by this endpoint). Set voice via `llm_config.voice` when creating/updating an agent.

Available xAI voices: `ara`, `rex`, `sal`, `eve`, `leo`

## Choosing the Right Voice

| Use Case | Recommended |
|----------|-------------|
| Appointments, surveys, support | Local voices (fast, clear) |
| Sales, relationship-building | ElevenLabs (natural, expressive) |
| Real-time conversations | xAI Grok Realtime (low latency) |

**Example agent with local voice:**
```json
{
  "name": "Appointment Agent",
  "tts_config": {
    "provider": "local",
    "voice_id": "nl_NL-pim-medium",
    "language": "nl"
  }
}
```
- [Get your domain](https://doc.voicedock.ai/docs/api/domains/getDomain): Retrieve your organization's configured email domain from Resend. Requires a Resend API key to be configured via BYOK (Bring Your Own Key). Returns null if no domain is configured.
- [Add a domain](https://doc.voicedock.ai/docs/api/domains/createDomain): Create a custom email domain in Resend for sending notifications from your organization. Requires a Resend API key configured via BYOK. You can only have one domain configured per organization.
- [Delete your domain](https://doc.voicedock.ai/docs/api/domains/deleteDomain): Remove your organization's configured email domain from both the database and Resend.
- [List available Resend domains](https://doc.voicedock.ai/docs/api/domains/listResendDomains): Fetch all domains configured in your Resend account. Use this to see which domains you can select for your organization's email notifications. Requires a Resend API key configured via BYOK.
- [Select and sync a Resend domain](https://doc.voicedock.ai/docs/api/domains/syncResendDomain): Select a domain from your Resend account to use for your organization's email notifications. This syncs the domain configuration to your organization.
- [Verify domain DNS records](https://doc.voicedock.ai/docs/api/domains/verifyDomain): Trigger domain verification in Resend to check if DNS records are correctly configured. This updates the domain status based on Resend's verification results.
- [Refresh domain status](https://doc.voicedock.ai/docs/api/domains/refreshDomain): Fetch the latest domain status from Resend and update your local configuration. Use this to check if verification has completed or if any records need attention.
- [Get usage logs](https://doc.voicedock.ai/docs/api/usage/getUsage): Retrieve your organization's usage logs with billing information and optional date filtering.
- [Get organization information](https://doc.voicedock.ai/docs/api/organization/getOrganization): Retrieve your organization details including balance, usage statistics, and resource counts. Use `include_children=true` to also list child organizations (for agencies).
- [Create organization](https://doc.voicedock.ai/docs/api/organization/createOrganization): Create a new organization. If `parent_org_id` is provided, creates a child organization that bills to the parent (for whitelabel use cases). The API key for the new organization is only returned once at creation time.
- [Get organization information (deprecated)](https://doc.voicedock.ai/docs/api/organization/getOrganizationLegacy): **Deprecated:** Use `/organizations` instead. Retrieve your organization details including balance, usage statistics, and resource counts.
- [Health check](https://doc.voicedock.ai/docs/api/system/getHealth): Returns the current health status of the API and its dependencies. No authentication required.
- [Dynamic assistant configuration webhook](https://doc.voicedock.ai/docs/api/webhooks/assistantRequestWebhook): 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.
- [Tool/Function Call](https://doc.voicedock.ai/docs/api/webhooks/toolCallsWebhook): 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"}
```
- [Call Status Update](https://doc.voicedock.ai/docs/api/webhooks/statusUpdateWebhook): Called when the call status changes. Use this to track call lifecycle.

**Statuses:**
- `in-progress`: Call connected, conversation started
- `ended`: Call ended normally (customer hung up)
- `ended-with-error`: Call ended due to an error

### 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

The response body is ignored.
- [End of Call Report](https://doc.voicedock.ai/docs/api/webhooks/endOfCallReportWebhook): Called after the call ends with a summary and optional structured analysis.

This is the most commonly used webhook for integrating call data into CRM systems.

**Payload includes:**
- Call duration in seconds
- AI-generated call summary
- Full conversation transcript (messages array)
- Structured analysis result (if `analysis_plan` was configured on the agent)
- Full assistant configuration including any custom metadata
- Recording URL (if recording is enabled)

### 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

This is especially useful for correlating call reports with your CRM records using the metadata you passed during `assistant-request`.

The response body is ignored.