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

​
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.
id
str
required
Unique identifier for the event, e.g. ev_8qm9JBCiTe7.
created_at
object
required
When the event was created.
agent_id
str
required
Version-specific identifier for the agent that handled the conversation, e.g. ca_8qm9JBCiTe7@v0.
livemode
bool
required
Whether the conversation is in livemode.
conversation_id
str
required
Unique identifier for the conversation, e.g. conv_8qm9JBCiTe7.
experimental
bool
required
Whether this event is experimental.
payload
object
required
See the breakdown of each payload type below.

​
conversation.setup

Sent before a conversation starts. This can be used as webhook to preload data relevant to the conversation.
type
string
required
The event’s type value is 'conversation.setup'
channel
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.
direction
'inbound' | 'outbound'
required
The direction of the conversation from the point of view of Operator.

​
conversation.started

Sent once the conversation has started.
type
string
required
The event’s type value is 'conversation.started'

​
conversation.ended

Sent when the conversation has ended.
type
string
required
The event’s type value is 'conversation.ended'
ended_by
'customer' | 'agent' | 'transfer'
The party that ended the conversation.

​
conversation.context.updated

Indicates the context has been updated on the agent side.
type
string
required
The event’s type value is 'conversation.context.updated'
data
dict[str, str]
required
Key-value pairs to merge into the conversation’s context.
trigger_response
bool
required
Whether the context update should trigger a response.

​
conversation.custom_fields.updated

Sent when conversation custom fields are modified.
type
string
required
The event’s type value is 'conversation.custom_fields.updated'
key
str
required
The custom field key that was updated.
new_value
str | bool
required
The new value of the custom field.
old_value
str | bool
required
The previous value of the custom field, if any.

​
agent.message.delta

Streaming partial message content as it’s being generated.
type
string
required
The event’s type value is 'agent.message.delta'
text_delta
str
required
The delta text of the message. Extends the message text within the same generation.
generation_id
str
required
The ID of the generation.

​
agent.message.completed

Sent when the agent finishes sending a message. Indicates that the generation has completed. Contains the full text of the message.
type
string
required
The event’s type value is 'agent.message.completed'
text
str
required
The full text of the message from the start of the generation.
interrupted
bool
required
Whether the generation was cut-off mid-stream e.g. due to an interruption by another speaker or an error.
has_tool_calls
bool
required
Whether this message triggered tool calls.
generation_id
str
required
The ID of the generation.

​
agent.tool_call.created

Sent when the agent triggers a tool call.
type
string
required
The event’s type value is 'agent.tool_call.created'
call_id
str
required
Unique ID for the tool call.
name
str
required
Name of the tool being invoked.
arguments
str
required
Raw JSON string of arguments to pass to the tool.

​
agent.tool_call.returned

Sent when the tool call returns a result.
type
string
required
The event’s type value is 'agent.tool_call.returned'
call_id
str
required
Unique ID for the tool call.
name
str
required
Name of the tool being invoked.
arguments
str
required
Raw JSON string of arguments to pass to the tool.
result
str
required
Raw JSON string of the tool call result.
error
str
Error message, if the call failed.

​
agent.notice.sent

Agent has sent a system-level notice (e.g. “This call may be recorded”).
type
string
required
The event’s type value is 'agent.notice.sent'
data
dict[str, str]
required
The data associated with the notice.

​
user.message.received

Acknowledgment that the user message was received.
type
string
required
The event’s type value is 'user.message.received'
text
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.

​
server.error

Emitted when a server-side error occurs during event handling.
type
string
required
The event’s type value is 'server.error'
error
str
required
The error message.
source_event_id
str
The ID of the client event that caused the error.

​
user.dtmf.received

EXPERIMENTAL: Sent when DTMF tones are received from the customer.
type
string
required
The event’s type value is 'user.dtmf.received'
digits
str
required
The DTMF digits received.

​
agent.dtmf.sent

EXPERIMENTAL: Sent when DTMF tones are sent to the customer.
type
string
required
The event’s type value is 'agent.dtmf.sent'
digits
str
required
The DTMF digits sent.

​
agent.customer.loaded

EXPERIMENTAL: Sent when customer information is loaded/identified. We should strengthen assumptions so that we always have an ID here.
type
string
required
The event’s type value is 'agent.customer.loaded'
name
str
The customer’s name, if available.
email
str
The customer’s email, if available.
phone_no
str
The customer’s email, if available.
customer_id
str
The customer ID identified, if available. Use the Customers API to retrieve details.

​
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
id
str
Optional ID used to track or correlate errors.
payload
object
required
See the breakdown of each payload type below.

​
user.message.send

Send a message from the user to the agent.
type
string
required
The event’s type value is 'user.message.send'
text
str
required
The message content, max 4096 characters.

​
conversation.context.update

Update the conversation context mid-session.
type
string
required
The event’s type value is 'conversation.context.update'
data
dict[str, str]
required
Key-value pairs to merge into the conversation’s context.

​
conversation.start

Start the conversation.
type
string
required
The event’s type value is 'conversation.start'

​
conversation.end

End the conversation.
type
string
required
The event’s type value is 'conversation.end'