> ## 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. # Real-time chat session > WebSocket API used in real-time conversations (e.g. those created with `chat_realtime`). Refer to [Conversation Events Schema](../conversation-events) for the full breakdown of events and payloads. Refer to [Real-time Events Example](../real-time-events-example) or [Post-analysis example](../post-analysis-example) for the usage example. ## AsyncAPI ````yaml api-reference/asyncapi.json conversations/{conversation_id}/session id: conversations/{conversation_id}/session title: Real-time chat session description: >- WebSocket API used in real-time conversations (e.g. those created with `chat_realtime`). Refer to [Conversation Events Schema](../conversation-events) for the full breakdown of events and payloads. Refer to [Real-time Events Example](../real-time-events-example) or [Post-analysis example](../post-analysis-example) for the usage example. servers: - id: production protocol: wss host: agent.app.operator.xyz bindings: [] variables: [] address: conversations/{conversation_id}/session?token={token} parameters: - id: conversation_id jsonSchema: type: string description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string required: true deprecated: false - id: token jsonSchema: type: string description: >- Ephemeral token returned by the server when the conversation was created. description: Ephemeral token returned by the server when the conversation was created. type: string required: true deprecated: false bindings: [] operations: - &ref_1 id: conversations/{conversation_id}/session.publish title: Conversations/{conversation_id}/session.publish description: Send events to the server type: receive messages: - &ref_3 id: publish.message.0 payload: - name: conversation.start description: Start the conversation. type: object properties: - name: id type: string description: Optional ID used to track or correlate errors. required: false - name: payload type: object description: Start the conversation. required: true properties: - name: type type: string enumValues: - conversation.start required: false headers: [] jsonPayloadSchema: type: object description: >- Events sent by the client to initiate or interact with a conversation. properties: id: type: string default: null description: Optional ID used to track or correlate errors. x-parser-schema-id: payload: description: Start the conversation. properties: type: default: conversation.start type: string enum: - conversation.start x-parser-schema-id: type: object x-parser-schema-id: required: - payload x-parser-schema-id: ConversationStartEvent title: conversation.start description: Start the conversation. example: |- { "id": "", "payload": { "type": "" } } bindings: [] extensions: - id: x-parser-unique-object-id value: publish.message.0 - &ref_4 id: publish.message.1 payload: - name: user.message.send description: Send a message from the user to the agent. type: object properties: - name: id type: string description: Optional ID used to track or correlate errors. required: false - name: payload type: object description: Send a message from the user to the agent. required: true properties: - name: type type: string enumValues: - user.message.send required: false - name: text type: string description: The message content, max 4096 characters. required: true headers: [] jsonPayloadSchema: type: object description: >- Events sent by the client to initiate or interact with a conversation. properties: id: type: string default: null description: Optional ID used to track or correlate errors. x-parser-schema-id: payload: description: Send a message from the user to the agent. properties: type: default: user.message.send type: string enum: - user.message.send x-parser-schema-id: text: description: The message content, max 4096 characters. type: string x-parser-schema-id: required: - text type: object x-parser-schema-id: required: - payload x-parser-schema-id: UserMessageSendEvent title: user.message.send description: Send a message from the user to the agent. example: |- { "id": "", "payload": { "type": "", "text": "" } } bindings: [] extensions: - id: x-parser-unique-object-id value: publish.message.1 - &ref_5 id: publish.message.2 payload: - name: conversation.context.update description: Update the conversation context mid-session. type: object properties: - name: id type: string description: Optional ID used to track or correlate errors. required: false - name: payload type: object description: Update the conversation context mid-session. required: true properties: - name: type type: string enumValues: - conversation.context.update required: false - name: data type: object description: Key-value pairs to merge into the conversation's context. required: true properties: [] headers: [] jsonPayloadSchema: type: object description: >- Events sent by the client to initiate or interact with a conversation. properties: id: type: string default: null description: Optional ID used to track or correlate errors. x-parser-schema-id: payload: description: Update the conversation context mid-session. properties: type: default: conversation.context.update type: string enum: - conversation.context.update x-parser-schema-id: data: properties: {} additionalProperties: type: string x-parser-schema-id: description: Key-value pairs to merge into the conversation's context. type: object x-parser-schema-id: required: - data type: object x-parser-schema-id: required: - payload x-parser-schema-id: ConversationContextUpdateEvent title: conversation.context.update description: Update the conversation context mid-session. example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: publish.message.2 - &ref_6 id: publish.message.3 payload: - name: conversation.end description: End the conversation. type: object properties: - name: id type: string description: Optional ID used to track or correlate errors. required: false - name: payload type: object description: End the conversation. required: true properties: - name: type type: string enumValues: - conversation.end required: false headers: [] jsonPayloadSchema: type: object description: >- Events sent by the client to initiate or interact with a conversation. properties: id: type: string default: null description: Optional ID used to track or correlate errors. x-parser-schema-id: payload: description: End the conversation. properties: type: default: conversation.end type: string enum: - conversation.end x-parser-schema-id: type: object x-parser-schema-id: required: - payload x-parser-schema-id: ConversationEndEvent title: conversation.end description: End the conversation. example: |- { "id": "", "payload": { "type": "" } } bindings: [] extensions: - id: x-parser-unique-object-id value: publish.message.3 bindings: [] extensions: &ref_0 - id: x-parser-unique-object-id value: conversations/{conversation_id}/session - &ref_2 id: conversations/{conversation_id}/session.subscribe title: Conversations/{conversation_id}/session.subscribe description: Receive events from the server type: send messages: - &ref_7 id: subscribe.message.0 payload: - name: conversation.started description: Sent once the conversation has started. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent once the conversation has started. required: true properties: - name: type type: string enumValues: - conversation.started required: false - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent once the conversation has started. properties: type: default: conversation.started type: string enum: - conversation.started x-parser-schema-id: type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ConversationStartedEvent title: conversation.started description: Sent once the conversation has started. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.0 - &ref_8 id: subscribe.message.1 payload: - name: conversation.setup description: >- Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: >- Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation. required: true properties: - name: type type: string enumValues: - conversation.setup required: false - name: channel type: object description: The channel of the conversation. required: false properties: [] - name: direction type: string description: The direction of the conversation. enumValues: - inbound - outbound required: true - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: >- Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation. properties: type: default: conversation.setup type: string enum: - conversation.setup x-parser-schema-id: channel: description: The channel of the conversation. type: object properties: {} x-parser-schema-id: direction: description: The direction of the conversation. enum: - inbound - outbound type: string x-parser-schema-id: required: - direction type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ConversationSetupEvent title: conversation.setup description: >- Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation. example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.1 - &ref_9 id: subscribe.message.2 payload: - name: conversation.context.updated description: Indicates the context has been updated on the agent side. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Indicates the context has been updated on the agent side. required: true properties: - name: type type: string enumValues: - conversation.context.updated required: false - name: data type: object description: Key-value pairs to merge into the conversation's context. required: true properties: [] - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Indicates the context has been updated on the agent side. properties: type: default: conversation.context.updated type: string enum: - conversation.context.updated x-parser-schema-id: data: properties: {} additionalProperties: type: string x-parser-schema-id: description: Key-value pairs to merge into the conversation's context. type: object x-parser-schema-id: required: - data type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ConversationContextUpdatedEvent title: conversation.context.updated description: Indicates the context has been updated on the agent side. example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.2 - &ref_10 id: subscribe.message.3 payload: - name: agent.notice.sent description: >- Agent has sent a system-level notice (e.g. "This call may be recorded"). type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: >- Agent has sent a system-level notice (e.g. "This call may be recorded"). required: true properties: - name: type type: string enumValues: - agent.notice.sent required: false - name: data type: object description: The data to send with the event. required: true properties: [] - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: >- Agent has sent a system-level notice (e.g. "This call may be recorded"). properties: type: default: agent.notice.sent type: string enum: - agent.notice.sent x-parser-schema-id: data: properties: {} additionalProperties: type: string x-parser-schema-id: description: The data to send with the event. type: object x-parser-schema-id: required: - data type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: AgentNoticeSentEvent title: agent.notice.sent description: >- Agent has sent a system-level notice (e.g. "This call may be recorded"). example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.3 - &ref_11 id: subscribe.message.4 payload: - name: agent.message.delta description: Streaming partial message content as it's being generated. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Streaming partial message content as it's being generated. required: true properties: - name: type type: string enumValues: - agent.message.delta required: false - name: text_delta type: string description: The delta text of the message. required: true - name: generation_id type: string description: The ID of the generation. required: true - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Streaming partial message content as it's being generated. properties: type: default: agent.message.delta type: string enum: - agent.message.delta x-parser-schema-id: text_delta: description: The delta text of the message. type: string x-parser-schema-id: generation_id: description: The ID of the generation. type: string x-parser-schema-id: required: - text_delta - generation_id type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: AgentMessageDeltaEvent title: agent.message.delta description: Streaming partial message content as it's being generated. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "text_delta": "", "generation_id": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.4 - &ref_12 id: subscribe.message.5 payload: - name: agent.message.completed description: Sent when the agent finishes sending a message. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent when the agent finishes sending a message. required: true properties: - name: type type: string enumValues: - agent.message.completed required: false - name: text type: string description: The text of the message. required: true - name: interrupted type: boolean description: Whether the generation was cut-off mid-stream. required: true - name: has_tool_calls type: boolean description: Whether this message triggered tool calls. required: true - name: generation_id type: string description: The ID of the generation. required: true - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent when the agent finishes sending a message. properties: type: default: agent.message.completed type: string enum: - agent.message.completed x-parser-schema-id: text: description: The text of the message. type: string x-parser-schema-id: interrupted: description: Whether the generation was cut-off mid-stream. type: boolean x-parser-schema-id: has_tool_calls: description: Whether this message triggered tool calls. type: boolean x-parser-schema-id: generation_id: description: The ID of the generation. type: string x-parser-schema-id: required: - text - interrupted - has_tool_calls - generation_id type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: AgentMessageCompletedEvent title: agent.message.completed description: Sent when the agent finishes sending a message. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "text": "", "interrupted": true, "has_tool_calls": true, "generation_id": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.5 - &ref_13 id: subscribe.message.6 payload: - name: agent.tool_call.created description: Sent when the agent triggers a tool call. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent when the agent triggers a tool call. required: true properties: - name: type type: string enumValues: - agent.tool_call.created required: false - name: call_id type: string description: Unique ID for the tool call. required: true - name: name type: string description: Name of the tool being invoked. required: true - name: arguments type: string description: Raw JSON string of arguments to pass to the tool. required: true - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent when the agent triggers a tool call. properties: type: default: agent.tool_call.created type: string enum: - agent.tool_call.created x-parser-schema-id: call_id: description: Unique ID for the tool call. type: string x-parser-schema-id: name: description: Name of the tool being invoked. type: string x-parser-schema-id: arguments: description: Raw JSON string of arguments to pass to the tool. type: string x-parser-schema-id: required: - call_id - name - arguments type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: AgentToolCallCreatedEvent title: agent.tool_call.created description: Sent when the agent triggers a tool call. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "call_id": "", "name": "", "arguments": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.6 - &ref_14 id: subscribe.message.7 payload: - name: agent.tool_call.returned description: Sent when the tool call returns a result. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent when the tool call returns a result. required: true properties: - name: type type: string enumValues: - agent.tool_call.returned required: false - name: call_id type: string description: Unique ID for the tool call. required: true - name: name type: string description: Name of the tool being invoked. required: true - name: arguments type: string description: Raw JSON string of arguments to pass to the tool. required: true - name: result type: string description: Raw JSON string of the tool call result. required: true - name: error type: string description: Error message, if the call failed. required: false - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent when the tool call returns a result. properties: type: default: agent.tool_call.returned type: string enum: - agent.tool_call.returned x-parser-schema-id: call_id: description: Unique ID for the tool call. type: string x-parser-schema-id: name: description: Name of the tool being invoked. type: string x-parser-schema-id: arguments: description: Raw JSON string of arguments to pass to the tool. type: string x-parser-schema-id: result: description: Raw JSON string of the tool call result. type: string x-parser-schema-id: error: type: string default: null description: Error message, if the call failed. x-parser-schema-id: required: - call_id - name - arguments - result type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: AgentToolCallReturnedEvent title: agent.tool_call.returned description: Sent when the tool call returns a result. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "call_id": "", "name": "", "arguments": "", "result": "", "error": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.7 - &ref_15 id: subscribe.message.8 payload: - name: user.message.received description: Acknowledgment that the user message was received. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Acknowledgment that the user message was received. required: true properties: - name: type type: string enumValues: - user.message.received required: false - name: text type: string description: The text of the message. required: true - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Acknowledgment that the user message was received. properties: type: default: user.message.received type: string enum: - user.message.received x-parser-schema-id: text: description: The text of the message. type: string x-parser-schema-id: required: - text type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: UserMessageReceivedEvent title: user.message.received description: Acknowledgment that the user message was received. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "text": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.8 - &ref_16 id: subscribe.message.9 payload: - name: conversation.custom_fields.updated description: Sent when conversation custom fields are modified. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent when conversation custom fields are modified. required: true properties: - name: type type: string enumValues: - conversation.custom_fields.updated required: false - name: key type: string description: The custom field key that was updated. required: true - name: new_value type: string description: The new value of the custom field. required: true - name: old_value type: string description: The previous value of the custom field, if applicable. required: false - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent when conversation custom fields are modified. properties: type: default: conversation.custom_fields.updated type: string enum: - conversation.custom_fields.updated x-parser-schema-id: key: description: The custom field key that was updated. type: string x-parser-schema-id: new_value: description: The new value of the custom field. type: string x-parser-schema-id: old_value: description: The previous value of the custom field, if applicable. type: string default: null x-parser-schema-id: required: - key - new_value type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ConversationCustomFieldsUpdatedEvent title: conversation.custom_fields.updated description: Sent when conversation custom fields are modified. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "key": "", "new_value": "", "old_value": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.9 - &ref_17 id: subscribe.message.10 payload: - name: conversation.ended description: Sent when the conversation has ended. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Sent when the conversation has ended. required: true properties: - name: type type: string enumValues: - conversation.ended required: false - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Sent when the conversation has ended. properties: type: default: conversation.ended type: string enum: - conversation.ended x-parser-schema-id: type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ConversationEndedEvent title: conversation.ended description: Sent when the conversation has ended. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.10 - &ref_18 id: subscribe.message.11 payload: - name: server.error description: Emitted when a server-side error occurs during event handling. type: object properties: - name: id type: string description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. required: true - name: created_at type: string description: When the event was created. required: true - name: agent_id type: string description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. required: true - name: livemode type: boolean description: Whether the conversation is in livemode. required: true - name: conversation_id type: string description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. required: true - name: payload type: object description: Emitted when a server-side error occurs during event handling. required: true properties: - name: type type: string enumValues: - server.error required: false - name: error type: string description: The error message. required: true - name: source_event_id type: string description: The ID of the client event that caused the error. required: false - name: experimental type: boolean description: Whether this event is experimental. required: true headers: [] jsonPayloadSchema: type: object description: >- Events emitted by the agent system in response to client input or internal agent logic. properties: id: description: Unique identifier for the event, e.g. `ev_8qm9JBCiTe7`. type: string x-parser-schema-id: created_at: description: When the event was created. format: date-time type: string x-parser-schema-id: agent_id: description: >- Version-specific identifier for the agent that handled the conversation, e.g. `ca_8qm9JBCiTe7@v0`. type: string x-parser-schema-id: livemode: description: Whether the conversation is in livemode. type: boolean x-parser-schema-id: conversation_id: description: Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string x-parser-schema-id: payload: description: Emitted when a server-side error occurs during event handling. properties: type: default: server.error type: string enum: - server.error x-parser-schema-id: error: description: The error message. type: string x-parser-schema-id: source_event_id: type: string default: null description: The ID of the client event that caused the error. x-parser-schema-id: required: - error type: object x-parser-schema-id: experimental: description: Whether this event is experimental. type: boolean x-parser-schema-id: required: - id - created_at - agent_id - livemode - conversation_id - payload - experimental x-parser-schema-id: ServerErrorEvent title: server.error description: Emitted when a server-side error occurs during event handling. example: |- { "id": "", "created_at": "", "agent_id": "", "livemode": true, "conversation_id": "", "payload": { "type": "", "error": "", "source_event_id": "" }, "experimental": true } bindings: [] extensions: - id: x-parser-unique-object-id value: subscribe.message.11 bindings: [] extensions: *ref_0 sendOperations: - *ref_1 receiveOperations: - *ref_2 sendMessages: - *ref_3 - *ref_4 - *ref_5 - *ref_6 receiveMessages: - *ref_7 - *ref_8 - *ref_9 - *ref_10 - *ref_11 - *ref_12 - *ref_13 - *ref_14 - *ref_15 - *ref_16 - *ref_17 - *ref_18 extensions: - id: x-parser-unique-object-id value: conversations/{conversation_id}/session securitySchemes: [] ````