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:

{}

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.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://your-api-server.com' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "message": { "type": "assistant-request", "timestamp": "2019-08-24T14:15:22.123Z", "call": { "id": "5c4d030f-43e3-4e65-899e-8148521e660f", "type": "inbound_phone_call", "status": "ringing", "pipeline": "standard" }, "phone_number": { "number": "+31850835037", "name": "HMS Sovereign Demo" }, "customer": { "number": "+31612345678" } } }'

Dynamic assistant configuration webhook

Response Modes

Custom Metadata

Request

Responses

Dynamic assistant configuration webhook

Response Modes#

Custom Metadata#

Request

Responses

Response Modes

Custom Metadata