Python SDK / Events & models
Events & models
The client is event-driven. Subscribe with
@client.on(ZeliEvent.…) and receive typed payloads. This page lists
every event and the models they carry.
from zeli import (
ZeliEvent, Message, MessageRole,
MessageStreamEvent, EmotionEvent, SessionInfo, ConnectionCloseCode,
)ZeliEvent
The enum has 14 members. See the events guide for payload examples.
| Value | Handler receives | Fires when |
|---|---|---|
CONNECTION_ESTABLISHED | — | The media connection is up. |
SESSION_READY | SessionInfo | The control-channel handshake completed. |
MESSAGE_RECEIVED | Message | A user or assistant message is finalized. |
MESSAGE_STREAM_EVENT_RECEIVED | MessageStreamEvent | An incremental transcript chunk arrives. |
MESSAGE_HISTORY_UPDATED | list[Message] | The transcript changed. |
AVATAR_SPEECH_STARTED | correlation_id: str | None | The avatar starts speaking. |
AVATAR_SPEECH_ENDED | correlation_id: str | None | The avatar stops speaking. |
TALK_STREAM_INTERRUPTED | — | A barge-in interrupted playback. |
EMOTION_DETECTED | EmotionEvent | The server classified an utterance's emotion. |
CONNECTION_CLOSED | code: str, reason: str | None | The session ended. |
SERVER_WARNING | message: str | The server sent a non-fatal warning. |
ERROR | error | A server-side or handler error occurred. |
USER_SPEECH_STARTED | correlation_id: str | None | Reserved — not currently emitted (see below). |
USER_SPEECH_ENDED | correlation_id: str | None | Reserved — not currently emitted (see below). |
USER_SPEECH_* are reserved
USER_SPEECH_STARTED and USER_SPEECH_ENDED exist in the
enum for a future mic-input path, but the client
does not currently emit them. Don't build logic that waits on
them firing.
Message
A finalized message in the transcript.
| Field | Type | Description |
|---|---|---|
id | str | Stable message id. |
role | MessageRole | USER, ASSISTANT, or SYSTEM. |
content | str | Full text. |
timestamp | str | Optional timestamp. |
interrupted | bool | Whether the message was cut off. |
MessageStreamEvent
An incremental transcript chunk (partial reply as it's spoken).
| Field | Type | Description |
|---|---|---|
id | str | Id of the message being assembled. |
role | MessageRole | Usually ASSISTANT. |
content | str | This chunk's text. |
content_index | int | Order of this chunk within the message. |
end_of_speech | bool | Whether this is the final chunk. |
interrupted | bool | Whether playback was interrupted. |
correlation_id | str | None | Ties the chunk to the originating command. |
MessageRole
An enum: USER, ASSISTANT, SYSTEM. Access the string via .value.
EmotionEvent
| Field | Type | Description |
|---|---|---|
emotion | str | Classified emotion for the utterance. |
correlation_id | str | None | Originating command id. |
SessionInfo
Delivered with SESSION_READY.
| Field | Type | Description |
|---|---|---|
session_id | str | Server-issued session id. |
ice_servers | list[dict] | ICE servers in effect. |
warnings | list[str] | Any startup warnings. |
ConnectionCloseCode
The code delivered with CONNECTION_CLOSED. An enum with values:
| Value | Meaning |
|---|---|
normal | Clean shutdown. |
server_closed | The server ended the session. |
webrtc_failure | The media transport failed. |
signalling_failure | The signalling/handshake failed. |
timeout | An operation or the connection timed out. |
error | An unspecified error ended the session. |