Call Event Hooks

Call Event Hooks are outbound HTTP webhooks that fire at specific points in a call’s lifecycle. When a call starts or ends, the platform sends a POST request with a JSON payload to every URL registered on that Assistant or Agent. Use them to trigger workflows, sync conversation data, send transcripts to your CRM, or any other external integration.

Hook types

Type	Fires when
`call_started`	The call is connected and audio has begun
`call_concluded`	The call has ended — includes the full conversation transcript, summaries, and call recording

Delivery

Request format

Webhooks are delivered as HTTP POST requests with Content-Type: application/json. Fields whose value is null are omitted from the payload.

Retry behaviour

The platform guarantees at-least-once delivery. If your endpoint returns an HTTP error status or does not respond within 30 seconds, the delivery is retried automatically.

Attempt	Backoff before next retry
1	1 minute
2	2 minutes
3	4 minutes
4	8 minutes
5	16 minutes
…	Doubles each time, capped at 24 hours
20	Final attempt — permanently marked `FAILED`

After 20 failed attempts no further retries occur.

Delivery states

Status	Meaning
`PENDING`	Awaiting delivery or scheduled for a retry
`SUCCEEDED`	Delivered successfully (2xx response received)
`FAILED`	All 20 attempts exhausted without success

Idempotency

Because deliveries are retried, your endpoint may receive the same event more than once. Use the callId field as an idempotency key on your side.

Payload reference

Shared fields

Every event payload contains these top-level fields.

Field	Type	Description
`type`	`string`	The event type: `call_started` or `call_concluded`
`callId`	`string`	UUID that uniquely identifies this call
`transport`	`object \| null`	Information about how the call was connected

Transport object

Field	Type	Present when
`type`	`string`	Always — `"sip"` or `"websocket"`
`calledNumber`	`string`	SIP only — the number that was dialled
`callingNumber`	`string`	SIP only — the caller’s number

SIP transport example

{
  "type": "sip",
  "calledNumber": "+4930123456",
  "callingNumber": "+4917612345678"
}

WebSocket transport example

{
  "type": "websocket"
}

`call_started`

Fired immediately when the call is connected. Fields

Field	Type	Description
`type`	`string`	`"call_started"`
`callId`	`string`	UUID of the call
`startedAt`	`number \| null`	Call start time — Unix timestamp in milliseconds
`transport`	`object \| null`	Transport info

Example payload

{
  "type": "call_started",
  "callId": "550e8400-e29b-41d4-a716-446655440000",
  "startedAt": 1740571200000,
  "transport": {
    "type": "sip",
    "calledNumber": "+4930123456",
    "callingNumber": "+4917612345678"
  }
}

`call_concluded`

Fired after the call ends. Contains the complete conversation history, LLM-generated summaries, and an optional call recording. Fields

Field	Type	Description
`type`	`string`	`"call_concluded"`
`callId`	`string`	UUID of the call
`startedAt`	`number \| null`	Call start time — Unix timestamp in milliseconds
`endedAt`	`number \| null`	Call end time — Unix timestamp in milliseconds
`shortSummary`	`string \| null`	Short LLM-generated summary of the call
`summary`	`string \| null`	Full LLM-generated summary of the call
`callRecording`	`string \| null`	Base64-encoded audio recording of the entire call
`transport`	`object \| null`	Transport info
`messages`	`array`	Ordered conversation history

Example payload

{
  "type": "call_concluded",
  "callId": "550e8400-e29b-41d4-a716-446655440000",
  "startedAt": 1740571200000,
  "endedAt": 1740571500000,
  "shortSummary": "Customer enquired about the Pro plan pricing.",
  "summary": "The customer called to ask about the pricing of the Pro subscription plan. The assistant explained the monthly and annual pricing options and offered to send a follow-up email with a detailed comparison.",
  "callRecording": "<base64-encoded-audio>",
  "transport": {
    "type": "sip",
    "calledNumber": "+4930123456",
    "callingNumber": "+4917612345678"
  },
  "messages": [
    {
      "type": "text",
      "role": "ASSISTANT",
      "timestamp": 1740571201000,
      "text": "Hello! How can I help you today?"
    },
    {
      "type": "text",
      "role": "USER",
      "timestamp": 1740571210000,
      "text": "Hi, I'd like to know about your Pro plan pricing."
    },
    {
      "type": "tool_call",
      "role": "TOOL_CALL",
      "timestamp": 1740571215000,
      "callId": "tool-abc-123",
      "toolName": "get_pricing",
      "parameters": {
        "plan": "pro"
      }
    },
    {
      "type": "tool_result",
      "role": "TOOL_CALL_RESULT",
      "timestamp": 1740571216000,
      "callId": "tool-abc-123",
      "toolName": "get_pricing",
      "text": "{\"monthly\": 49, \"annual\": 39}"
    },
    {
      "type": "text",
      "role": "ASSISTANT",
      "timestamp": 1740571220000,
      "text": "The Pro plan is $49 per month, or $39 per month on an annual subscription."
    }
  ]
}

Messages

The messages array contains every turn of the conversation in chronological order. Each element has a type discriminator field. Shared message fields

Field	Type	Description
`type`	`string`	Message type: `text`, `audio`, `tool_call`, or `tool_result`
`role`	`string`	Who produced this message
`timestamp`	`number`	Unix timestamp in milliseconds

Role values

Role	Description
`USER`	Speech input from the human caller
`ASSISTANT`	Response generated by the AI assistant
`SYSTEM`	An internal system-level message
`TOOL_CALL`	A tool invocation initiated by the LLM
`TOOL_CALL_RESULT`	The result returned by a tool
`UNKNOWN`	Role could not be determined

Message types

text

Represents a spoken utterance transcribed to text — from the caller (USER) or the assistant (ASSISTANT).

Field	Type	Description
`type`	`string`	`"text"`
`role`	`string`	`USER`, `ASSISTANT`, `SYSTEM`, or `UNKNOWN`
`timestamp`	`number`	Unix timestamp in milliseconds
`text`	`string`	Transcribed or generated text content

{
  "type": "text",
  "role": "USER",
  "timestamp": 1740571210000,
  "text": "Hi, I'd like to know about your Pro plan pricing."
}

audio

Represents a message that exists only as raw audio with no transcription available.

Field	Type	Description
`type`	`string`	`"audio"`
`role`	`string`	`USER`, `ASSISTANT`, `SYSTEM`, or `UNKNOWN`
`timestamp`	`number`	Unix timestamp in milliseconds
`audio`	`string`	Base64-encoded raw audio data

{
  "type": "audio",
  "role": "USER",
  "timestamp": 1740571210000,
  "audio": "<base64-encoded-audio>"
}

tool_call

Recorded when the LLM decides to invoke a tool during the conversation.

Field	Type	Description
`type`	`string`	`"tool_call"`
`role`	`string`	Always `"TOOL_CALL"`
`timestamp`	`number`	Unix timestamp in milliseconds
`callId`	`string`	Correlates this call with its result
`toolName`	`string`	The name of the tool that was invoked
`parameters`	`object`	The arguments passed to the tool by the LLM

{
  "type": "tool_call",
  "role": "TOOL_CALL",
  "timestamp": 1740571215000,
  "callId": "tool-abc-123",
  "toolName": "get_pricing",
  "parameters": {
    "plan": "pro"
  }
}

tool_result

Recorded when a tool returns its result back to the LLM.

Field	Type	Description
`type`	`string`	`"tool_result"`
`role`	`string`	Always `"TOOL_CALL_RESULT"`
`timestamp`	`number`	Unix timestamp in milliseconds
`callId`	`string`	Matches the `callId` of the originating tool call
`toolName`	`string`	The name of the tool that produced the result
`text`	`string`	The tool’s return value as a plain string

{
  "type": "tool_result",
  "role": "TOOL_CALL_RESULT",
  "timestamp": 1740571216000,
  "callId": "tool-abc-123",
  "toolName": "get_pricing",
  "text": "{\"monthly\": 49, \"annual\": 39}"
}

Configuration

Call Event Hooks are configured per Assistant or Agent — they are not a standalone resource.

Dashboard

Open the Assistant or Agent you want to configure.
Navigate to the Event Hooks section.
Click Add Hook (Hinzufügen), select the hook type, and enter your target URL.
Save. The hook is now active for all future calls on that Assistant or Agent.

To update a hook, edit the URL in place and save. To remove a hook, delete it from the list and save.

REST API

Hooks are managed through the Assistant and Agent endpoints. The examples below use the Assistant path — the Agent path follows the exact same structure.

/api/v1/vendors/{vendorId}/organizations/{organizationId}/assistants
/api/v1/vendors/{vendorId}/organizations/{organizationId}/agents

Read hooks — GET /{assistantId}

Retrieve the full Assistant configuration including its hooks.

GET /api/v1/vendors/{vendorId}/organizations/{organizationId}/assistants/{assistantId}

The callEventHooks array in the response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Assistant",
  "callEventHooks": [
    {
      "id": "b00bface-1337-badd-cafe-d00df00dcafe",
      "type": "call_started",
      "parameters": {
        "url": "https://your-server.com/hooks/call-started"
      }
    },
    {
      "id": "deadbeef-cafe-babe-feed-faceabadb001",
      "type": "call_concluded",
      "parameters": {
        "url": "https://your-server.com/hooks/call-concluded"
      }
    }
  ]
}

Each hook object:

Field	Type	Description
`id`	`string`	UUID of the hook instance
`type`	`string`	`"call_started"` or `"call_concluded"`
`parameters.url`	`string`	The target URL for this hook

Create hooks — POST /assistants

Include callEventHooks in the request body when creating an Assistant. Omit the id — it is assigned by the platform.

POST /api/v1/vendors/{vendorId}/organizations/{organizationId}/assistants
Content-Type: application/json

{
  "name": "Support Assistant",
  "callEventHooks": [
    {
      "type": "call_started",
      "parameters": {
        "url": "https://your-server.com/hooks/call-started"
      }
    },
    {
      "type": "call_concluded",
      "parameters": {
        "url": "https://your-server.com/hooks/call-concluded"
      }
    }
  ]
}

Returns the full Assistant object including the assigned hook id values.

Update hooks — PUT /{assistantId}

The PUT endpoint replaces the entire callEventHooks array. The behaviour depends on whether id is included for each hook:

Scenario	What to do
Update an existing hook’s URL	Include the hook’s `id` with the new `url`
Add a new hook	Omit the `id` field
Remove a hook	Leave it out of the array

PUT /api/v1/vendors/{vendorId}/organizations/{organizationId}/assistants/{assistantId}
Content-Type: application/json

{
  "name": "Support Assistant",
  "callEventHooks": [
    {
      "id": "b00bface-1337-badd-cafe-d00df00dcafe",
      "type": "call_started",
      "parameters": {
        "url": "https://your-updated-server.com/hooks/call-started"
      }
    },
    {
      "type": "call_concluded",
      "parameters": {
        "url": "https://your-server.com/hooks/call-concluded"
      }
    }
  ]
}

In this example:

The call_started hook with the given id is updated with the new URL.
The call_concluded entry has no id, so a new hook is created.
Any previously existing hooks not listed are removed.

Returns 200 OK with an empty success body.

The same operations apply to Agents at /api/v1/vendors/{vendorId}/organizations/{organizationId}/agents/{agentId}. The request and response shapes for callEventHooks are identical.

Overview

Realtime

Assistants

Agents

Agent Tasks

Organizations

Plans

Vendors

SIP Credentials

SIP Phone Numbers

Call Event Hooks

Hook types

Delivery

Request format

Retry behaviour

Delivery states

Idempotency

Payload reference

Shared fields

Transport object

`call_started`

`call_concluded`

Messages

Configuration

Dashboard

REST API

Overview

Realtime

Call Event Hooks

Assistants

Agents

Agent Tasks

Organizations

Plans

Vendors

SIP Credentials

SIP Phone Numbers

​Hook types

​Delivery

​Request format

​Retry behaviour

​Delivery states

​Idempotency

​Payload reference

​Shared fields

​Transport object

​call_started

​call_concluded

​Messages

​Configuration

​Dashboard

​REST API

Hook types

Delivery

Request format

Retry behaviour

Delivery states

Idempotency

Payload reference

Shared fields

Transport object

`call_started`

`call_concluded`

Messages

Configuration

Dashboard

REST API