Assistant Request Webhook

Called before an inbound call is answered, allowing dynamic assistant configuration based on caller information.

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

When It's Called

Inbound call arrives at your phone number
Assistant 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 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)

app.post('/webhooks/assistant-request', async (req, res) => {
  const { message } = req.body;
  const customerNumber = message.customer.number;
  
  // Look up customer in CRM
  const customer = await lookupCustomer(customerNumber);
  
  if (!customer) {
    // New caller - use default
    return res.json({});
  }
  
  // Personalize for known customer
  return res.json({
    assistant: {
      first_message: `Hello ${customer.name}, welcome back! How can I help?`,
      llm_config: {
        messages: [
          {
            role: "system",
            content: `You are speaking with ${customer.name}. Customer since ${customer.since}. ${customer.notes}`
          }
        ]
      }
    }
  });
});

See Assistant Request Webhook API for complete schema details.

On this page