Client Messages, Server Messages & Hook Configuration

Overview

Two assistant-level arrays control which real-time messages get sent where during a call: serverMessages (sent to your server via webhook) and clientMessages (sent to client-side SDKs, such as a web or mobile widget). This page covers how to configure both arrays, plus how assistant hooks tie into the same message-and-event picture. For the full hook trigger/action reference, see Hooks & Call Control; for the full webhook event catalog and handler examples, see Webhooks & Events.

serverMessages defines which event types your assistant sends to your configured server URL. It is now an array of message-type objects with no fixed restriction beyond matching the server message schema — you must explicitly include this property when creating or updating an assistant, since it's no longer inferred automatically.

A representative list of server message types:

{
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ]
}

clientMessages controls which message types are pushed to client-side SDKs (for example, a web widget) while the call is in progress, so your UI can react in real time — updating a transcript view, showing when the assistant is speaking, or reflecting call status changes. Configure it the same way, as an array on the assistant object:

{
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ]
}

Because serverMessages and clientMessages are independent arrays, you can subscribe your server and your client UI to different subsets of the same underlying events.

Here's an assistant configured with both arrays at once:

{
  "name": "My Assistant",
  "model": { "provider": "openai", "model": "gpt-4o", "messages": [{ "role": "system", "content": "You are a helpful assistant." }] },
  "voice": { "provider": "11labs", "voiceId": "N2lVS1w4EtoT3dr4eOWO" },
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ],
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ]
}

Hooks are a separate but related mechanism: rather than pushing an event to your own server or client, a hook lets the assistant take a deterministic action itself when a trigger fires, without needing a round trip to your infrastructure. Hooks are configured as an array in the assistant's hooks field. Each hook has an on field naming the trigger event, a do array of actions to run, and optional options such as timeoutSeconds, triggerMaxCount, and triggerResetMode for triggers that can fire more than once in a call. Actions in the do array include say.exact or say.prompt (speak a fixed or model-generated line) and tool (execute a tool, such as ending the call). See Hooks & Call Control for the complete trigger and action reference.

An idle-message hook, prompting the caller if they've gone quiet partway through the call:

{
  "on": "customer.speech.timeout",
  "options": { "timeoutSeconds": 20, "triggerMaxCount": 2, "triggerResetMode": "onUserSpeech" },
  "do": [
    { "type": "say", "exact": "Are you still there? Take your time." }
  ]
}

An end-call-after-silence hook, closing the call after repeated silence with a spoken warning first:

{
  "on": "customer.speech.timeout",
  "options": { "timeoutSeconds": 30, "triggerMaxCount": 3, "triggerResetMode": "onUserSpeech" },
  "do": [
    { "type": "say", "exact": "I haven't heard from you, so I'll go ahead and end the call now." },
    { "type": "tool", "tool": { "type": "endCall" } }
  ]
}

Together, serverMessages/clientMessages and hooks give you two complementary tools: message arrays for observing and reacting to a call from your own systems, and hooks for building automated behavior directly into the assistant.