Skip to content

Events & Content

RoomEvent

Bases: BaseModel

A single event in a room conversation.

EventSource

Bases: BaseModel

Origin information for an event.

verification class-attribute instance-attribute

verification = None

The sender's verification when the event was received (RFC §11.7.3); None where none applies (an unidentified sender, an agent, the framework).

EventContent module-attribute

EventContent = Annotated[TextContent | RichContent | MediaContent | LocationContent | AudioContent | VideoContent | CompositeContent | SystemContent | TemplateContent | EditContent | DeleteContent | ToolCallContent, Field(discriminator='type')]

Content Types

TextContent

Bases: BaseModel

Plain text message content.

RichContent

Bases: BaseModel

Rich formatted content (HTML/Markdown).

MediaContent

Bases: BaseModel

Media attachment content.

url is a link (http, https), a data: URI, or a reference: <scheme>://… in a scheme the application chooses, naming a media it holds and resolves for the AI channels (RFC §6.4). A scheme a reader could fetch or open itself (file, ftp) or run (javascript, vbscript) is refused, and so is a reference a path reader could follow (a one-letter scheme, a .. segment, a backslash): some transports read a URL they are handed as a local path.

AudioContent

Bases: BaseModel

Audio message content.

VideoContent

Bases: BaseModel

Video message content.

LocationContent

Bases: BaseModel

Geographic location content.

CompositeContent

Bases: BaseModel

Multi-part content combining multiple content types.

SystemContent

Bases: BaseModel

System-generated content.

TemplateContent

Bases: BaseModel

Pre-approved template content (WhatsApp Business, etc.).

Framework Events

FrameworkEvent

Bases: BaseModel

An event emitted by the framework for observability.

SessionStartedEvent dataclass

SessionStartedEvent(room_id, channel_id, channel_type, participant_id, session=None, timestamp=_utcnow())

A session has started on any channel type.

For voice channels this fires when the audio path is live and ready to send/receive (same dual-signal timing as the former ON_VOICE_SESSION_READY). For text-based transport channels it fires when the inbound pipeline auto-creates a new room for a first message.

This is the safe point to send greetings or start telemetry.

room_id instance-attribute

room_id

The room this session belongs to.

channel_id instance-attribute

channel_id

The channel that triggered the session.

channel_type instance-attribute

channel_type

The type of channel (VOICE, SMS, WEBSOCKET, etc.).

participant_id instance-attribute

participant_id

The participant whose session started.

session class-attribute instance-attribute

session = None

The VoiceSession for voice channels, None for text channels.

timestamp class-attribute instance-attribute

timestamp = field(default_factory=_utcnow)

When the session started.

ProtocolTrace dataclass

ProtocolTrace(channel_id, direction, protocol, summary, raw=None, metadata=dict(), timestamp=(lambda: now(UTC))(), session_id=None, room_id=None)

A single protocol-level trace event emitted by a channel.

Captures raw protocol data (SIP, RTP, WebSocket, HTTP, etc.) flowing through a channel. Disabled by default; zero overhead when no observers are registered.

Attributes:

Name Type Description
channel_id str

Which channel emitted this trace.

direction Literal['inbound', 'outbound']

Whether the message was inbound or outbound.

protocol str

Protocol identifier (e.g. "sip", "rtp", "ws", "http").

summary str

Human-readable one-liner (e.g. "INVITE sip:+1555@pbx").

raw bytes | str | None

Full payload bytes or string (optional for high-freq traces).

metadata dict[str, Any]

Protocol-specific extras (codec info, headers, etc.).

timestamp datetime

When the trace was captured.

session_id str | None

For session-scoped traces (voice sessions, etc.).

room_id str | None

Set by emitter if known at emit time.

RoomContext

Bases: BaseModel

Contextual information about a room for hook and channel processing.

recent_events is the room's tail in ascending order: its last element is the most recent event the context knows about. Every consumer reads it that way — memory providers slice [-N:], the inbound pipeline appends the freshly committed event at the end, and hooks scanning for "the latest X" iterate it reversed. A producer building a RoomContext by hand owes it the same shape.

The room, bindings, participants and events it holds are the store's snapshots (RFC §14.4): a hook or a channel treats them as frozen, and changes the room through the kit (update_room_metadata()), never in place. InMemoryStore shares them, so a change made in place would reach the store behind the write interface's back.

author_register class-attribute instance-attribute

author_register = None

The room's register of authors (RFC §6.4, §10.1 step 12), which the labels of its turns read their ranks from, as the store keeps it apart from the room's metadata: its digests name the room's senders to whoever tries every phone number or name, so it reaches the runtime's readers and a remote executor here, never a client through room.metadata. None when the room holds none or the context was built without it.

other_channels

other_channels(exclude_channel_id)

Get all bindings except the specified channel.

channels_by_type

channels_by_type(channel_type)

Get all bindings of a specific channel type.

get_binding

get_binding(channel_id)

Get the binding for a specific channel.