> ## Documentation Index
> Fetch the complete documentation index at: https://operator.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation events schema

> Detailed breakdown of the conversation events.

export const ApiProperty = ({name, type, children, required = false}) => {
  return <div className="py-6 border-b border-gray-200 dark:border-gray-700">
      <div className="flex font-mono text-sm group/param-head param-head break-all relative">
        <div className="flex-1 flex content-start py-0.5 mr-5">
          <div className="flex items-center flex-wrap gap-2">
            <div className="font-semibold text-primary dark:text-primary-light cursor-pointer overflow-wrap-anywhere" data-component-part="field-name">
              {name}
            </div>
            <div className="inline items-center gap-2 text-xs font-medium [&_div]:inline [&_div]:mr-2 [&_div]:leading-5" data-component-part="field-meta">
              <div className="flex items-center px-2 py-0.5 rounded-md bg-gray-100/50 dark:bg-white/5 text-gray-600 dark:text-gray-200 font-medium break-all" data-component-part="field-info-pill">
                <span>{type}</span>
              </div>
              {required && <div className="px-2 py-0.5 rounded-md bg-red-100/50 dark:bg-red-400/10 text-red-600 dark:text-red-300 font-medium whitespace-nowrap" data-component-part="field-required-pill">
                  required
                </div>}
            </div>
          </div>
        </div>
      </div>
      <div className="mt-4">
        <div className="prose prose-sm prose-gray dark:prose-invert">
          <p className="whitespace-pre-line">{children}</p>
        </div>
      </div>
    </div>;
};

This page provides a detailed breakdown of the conversation events and their payloads. For the usage examples refer to the following examples:

* See the [Real-time events example](/docs/api-reference/real-time-events-example) for the live transcript usage.
* See the [Post-analysis example](/docs/api-reference/post-analysis-example) for a simplified server-side usage.

## Server Events

Events emitted by the agent system in response to client input or internal agent logic.

Typically the conversation begins with a setup when the agent fetches the conversation context and initializes.

The conversation's 'start' and 'end' indicate the live session's bounds - when the user was actively connected through phone or chat. In case of an async chat the bounds are determined automatically.

User's and agent's messages are recorded as they are processed by the agent. Agent's speech is streamed as partial updates, terminated with a final message. User's messages are captured as a single event.

<ApiProperty name="id" type="str" required>Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`.</ApiProperty>

<ApiProperty name="created_at" type="object" required>When the event was created.</ApiProperty>

<ApiProperty name="agent_id" type="str" required>Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`.</ApiProperty>

<ApiProperty name="livemode" type="bool" required>Whether the conversation is in livemode.</ApiProperty>

<ApiProperty name="conversation_id" type="str" required>Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`.</ApiProperty>

<ApiProperty name="experimental" type="bool" required>Whether this event is experimental.</ApiProperty>

<ApiProperty name="payload" type="object" required>See the breakdown of each payload type below.</ApiProperty>

### `conversation.setup`

Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.setup'`</ApiProperty>

<ApiProperty name="channel" type="object" required>The channel of the conversation. The `type` field is one of `'phone'`, `'chat_realtime'`, `'chat_async'`. Additional fields supply auxiliary information when applicable: `callee_no`, `caller_no`, `recording_url`.</ApiProperty>

<ApiProperty name="direction" type="'inbound' | 'outbound'" required>The direction of the conversation from the point of view of Operator.</ApiProperty>

### `conversation.started`

Sent once the conversation has started.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.started'`</ApiProperty>

### `conversation.ended`

Sent when the conversation has ended.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.ended'`</ApiProperty>

<ApiProperty name="ended_by" type="'customer' | 'agent' | 'transfer'">The party that ended the conversation.</ApiProperty>

### `conversation.context.updated`

Indicates the context has been updated on the agent side.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.context.updated'`</ApiProperty>

<ApiProperty name="data" type="dict[str, str]" required>Key-value pairs to merge into the conversation's context.</ApiProperty>

<ApiProperty name="trigger_response" type="bool" required>Whether the context update should trigger a response.</ApiProperty>

### `conversation.custom_fields.updated`

Sent when conversation custom fields are modified.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.custom_fields.updated'`</ApiProperty>

<ApiProperty name="key" type="str" required>The custom field key that was updated.</ApiProperty>

<ApiProperty name="new_value" type="str | bool" required>The new value of the custom field.</ApiProperty>

<ApiProperty name="old_value" type="str | bool" required>The previous value of the custom field, if any.</ApiProperty>

### `agent.message.delta`

Streaming partial message content as it's being generated.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.message.delta'`</ApiProperty>

<ApiProperty name="text_delta" type="str" required>The delta text of the message. Extends the message text within the same generation.</ApiProperty>

<ApiProperty name="generation_id" type="str" required>The ID of the generation.</ApiProperty>

### `agent.message.completed`

Sent when the agent finishes sending a message. Indicates that the generation has completed. Contains the full text of the message.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.message.completed'`</ApiProperty>

<ApiProperty name="text" type="str" required>The full text of the message from the start of the generation.</ApiProperty>

<ApiProperty name="interrupted" type="bool" required>Whether the generation was cut-off mid-stream e.g. due to an interruption by another speaker or an error.</ApiProperty>

<ApiProperty name="has_tool_calls" type="bool" required>Whether this message triggered tool calls.</ApiProperty>

<ApiProperty name="generation_id" type="str" required>The ID of the generation.</ApiProperty>

### `agent.tool_call.created`

Sent when the agent triggers a tool call.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.tool_call.created'`</ApiProperty>

<ApiProperty name="call_id" type="str" required>Unique ID for the tool call.</ApiProperty>

<ApiProperty name="name" type="str" required>Name of the tool being invoked.</ApiProperty>

<ApiProperty name="arguments" type="str" required>Raw JSON string of arguments to pass to the tool.</ApiProperty>

### `agent.tool_call.returned`

Sent when the tool call returns a result.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.tool_call.returned'`</ApiProperty>

<ApiProperty name="call_id" type="str" required>Unique ID for the tool call.</ApiProperty>

<ApiProperty name="name" type="str" required>Name of the tool being invoked.</ApiProperty>

<ApiProperty name="arguments" type="str" required>Raw JSON string of arguments to pass to the tool.</ApiProperty>

<ApiProperty name="result" type="str" required>Raw JSON string of the tool call result.</ApiProperty>

<ApiProperty name="error" type="str">Error message, if the call failed.</ApiProperty>

### `agent.notice.sent`

EXPERIMENTAL: Agent has sent a system-level notice (e.g. "This call may be recorded").

<ApiProperty name="type" type="string" required>The event's type value is `'agent.notice.sent'`</ApiProperty>

<ApiProperty name="data" type="object" required>The notices sent.</ApiProperty>

### `user.message.received`

Acknowledgment that the user message was received.

<ApiProperty name="type" type="string" required>The event's type value is `'user.message.received'`</ApiProperty>

<ApiProperty name="text" type="str" required>The text of the message as received by the agent. For voice conversations, this is a transcription of the speech, which might be inaccurate.</ApiProperty>

### `server.error`

Emitted when a server-side error occurs during event handling.

<ApiProperty name="type" type="string" required>The event's type value is `'server.error'`</ApiProperty>

<ApiProperty name="error" type="str" required>The error message.</ApiProperty>

<ApiProperty name="source_event_id" type="str">The ID of the client event that caused the error.</ApiProperty>

### `user.dtmf.received`

EXPERIMENTAL: Sent when DTMF tones are received from the customer.

<ApiProperty name="type" type="string" required>The event's type value is `'user.dtmf.received'`</ApiProperty>

<ApiProperty name="digits" type="str" required>The DTMF digits received.</ApiProperty>

### `agent.dtmf.sent`

EXPERIMENTAL: Sent when DTMF tones are sent to the customer.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.dtmf.sent'`</ApiProperty>

<ApiProperty name="digits" type="str" required>The DTMF digits sent.</ApiProperty>

### `agent.customer.loaded`

EXPERIMENTAL: Sent when customer information is loaded/identified.
We should strengthen assumptions so that we always have an ID here.

<ApiProperty name="type" type="string" required>The event's type value is `'agent.customer.loaded'`</ApiProperty>

<ApiProperty name="name" type="str">The customer's name, if available.</ApiProperty>

<ApiProperty name="email" type="str">The customer's email, if available.</ApiProperty>

<ApiProperty name="phone_no" type="str">The customer's email, if available.</ApiProperty>

<ApiProperty name="customer_id" type="str">The customer ID identified, if available. Use the Customers API to retrieve details.</ApiProperty>

## Client Events

Events sent by the clients over API to initiate or interact with a conversation. Can only be sent to a conversation that has not ended yet.

Example use-cases:

* `conversation.end` to terminate the conversation early
* `conversation.context.update` to notify the agent of an internal event that is relevant to the conversation, e.g. "user verification completed"
* `user.message.send` to notify the agent of a user message sent through other means, e.g. a separate chat system, slack, etc

<ApiProperty name="id" type="str">Optional ID used to track or correlate errors.</ApiProperty>

<ApiProperty name="payload" type="object" required>See the breakdown of each payload type below.</ApiProperty>

### `user.message.send`

Send a message from the user to the agent.

<ApiProperty name="type" type="string" required>The event's type value is `'user.message.send'`</ApiProperty>

<ApiProperty name="text" type="str" required>The message content, max 4096 characters.</ApiProperty>

### `conversation.context.update`

Update the conversation context mid-session.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.context.update'`</ApiProperty>

<ApiProperty name="data" type="dict[str, str]" required>Key-value pairs to merge into the conversation's context.</ApiProperty>

### `conversation.start`

Start the conversation.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.start'`</ApiProperty>

### `conversation.end`

End the conversation.

<ApiProperty name="type" type="string" required>The event's type value is `'conversation.end'`</ApiProperty>