Assistant request

Called before an inbound call is answered, allowing you to dynamically configure the agent based on caller information.

When It's Called

Inbound call arrives at your phone number

Agent has webhook_url configured with assistant-request event enabled

HMS Sovereign sends POST request to your webhook

Your endpoint responds with configuration overrides (or empty object)

Call is answered with the configured settings

Timeout

Your endpoint must respond within 5 seconds. If it doesn't respond in time, the call proceeds with the default agent configuration.

Request Payload

{
  "message": {
    "type": "assistant-request",
    "timestamp": "2025-12-13T12:00:00.000Z",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "status": "ringing"
    },
    "phone_number": {
      "number": "+31850835037",
      "name": "HMS Sovereign Demo"
    },
    "customer": {
      "number": "+31612345678"
    }
  }
}

Response Options

Use Default Configuration

Return an empty object to use the default agent configuration:

{}

Personalize Greeting

{
  "assistant": {
    "first_message": "Hallo Jan, leuk dat je belt! Hoe kan ik je helpen?"
  }
}

Override LLM Configuration

{
  "assistant": {
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "Je spreekt met Jan de Vries, een VIP klant. Wees extra behulpzaam."
        }
      ]
    }
  }
}

Set Call Duration Limit

{
  "max_duration_seconds": 300
}

Reject the Call

Return an error message to reject the call. The message is spoken to the caller:

{
  "error": "Sorry, we zijn op dit moment gesloten. Bel terug tijdens kantooruren."
}

Enable Call Analysis

{
  "assistant": {
    "analysis_plan": {
      "structured_data_plan": {
        "enabled": true,
        "schema": {
          "type": "object",
          "properties": {
            "intent": { "type": "string" },
            "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] },
            "appointment_booked": { "type": "boolean" }
          }
        },
        "messages": [
          {
            "role": "system",
            "content": "Analyze the call transcript according to the schema: {{schema}}"
          },
          {
            "role": "user",
            "content": "Transcript: {{transcript}}"
          }
        ]
      }
    }
  }
}

Use Cases

CRM Integration: Look up caller in your CRM and personalize greeting

Business Hours: Reject calls outside business hours

VIP Handling: Use premium model for important customers

A/B Testing: Route callers to different agent configurations

Language Detection: Adjust language based on caller's region

Example Implementation (Node.js)

See AssistantRequestPayload Schema and AssistantRequestResponse Schema for complete details.

When It's Called#

Timeout#

Request Payload#

Response Options#

Use Default Configuration#

Personalize Greeting#

Override LLM Configuration#

Set Call Duration Limit#

Reject the Call#

Enable Call Analysis#

Use Cases#

Example Implementation (Node.js)#