1. 🪝 Webhooks
  • HMS Sovereign Introduction
  • 🚀 Get Started
    • Authentication
    • Quickstart
  • 🧩 Core Concepts
    • Assistants
    • Calls
    • Phone Numbers
    • Webhooks
  • 🏗️ Platform
    • Privacy policy
    • Dashboard Security
    • Data Processing Agreement (DPA)
    • Billing and Credits
    • EU Data Sovereignty
    • Voice Selection
    • Whitelabel Portal
  • 🛠️ SDKs
    • Node.js SDK
  • 🪝 Webhooks
    • Assistant Request
    • End of Call Report
    • Webhooks Overview
    • Webhook Security
    • Status Update
    • Tool Calls
  • ⚙️ Configuration
    • Analysis Templates
    • Custom Tools
    • SIP Trunks
    • Tool Templates
  • ✨ Features
    • AI Generation
    • Autonomous Silence Handling
    • Call Analysis
    • Call Transfers
    • Campaigns Setup
    • Outbound Campaigns
    • Voicemail Detection
    • Web Calls
    • Privacy & Compliance Features
  • 🔗 Integrations
    • MCP Server
    • BYOK Setup
    • Provider Pricing
    • xAI Grok Integration
  • 📖 Reference
    • Error Codes
    • Rate Limits
    • Troubleshooting
Book a meeting
Linkedin
Github
📄 Documentation
🔌 API Reference🤖 MCP🕐 Changelog📦 SDK🟢 Status
📄 Documentation
🔌 API Reference🤖 MCP🕐 Changelog📦 SDK🟢 Status
  1. 🪝 Webhooks

Assistant Request

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

When It's Called#

1.
Inbound call arrives at your phone number
2.
Assistant has webhook_url configured with assistant-request event enabled
3.
HMS Sovereign sends POST request to your webhook
4.
Your endpoint responds with configuration overrides (or empty object)
5.
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 assistant 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 assistant configuration:
{}

Personalize Greeting#

{
  "assistant": {
    "first_message": "Hello John, great to hear from you! How can I help?"
  }
}

Override LLM Configuration#

{
  "assistant": {
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are speaking with John Smith, a VIP customer. Be extra helpful."
        }
      ]
    }
  }
}

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 are currently closed. Please call back during business hours."
}

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 assistant configurations
Language Detection: Adjust language based on caller's region

Example Implementation (Node.js)#

See AssistantRequestPayload Schema and AssistantRequestResponse Schema for complete details.
Modified at 2026-03-28 09:30:28
Previous
Node.js SDK
Next
End of Call Report
Built with