Events & Content

RoomEvent

Bases: BaseModel

A single event in a room conversation.

EventSource

Bases: BaseModel

Origin information for an event.

EventContent module-attribute

EventContent = Annotated[TextContent | RichContent | MediaContent | LocationContent | AudioContent | VideoContent | CompositeContent | SystemContent | TemplateContent | EditContent | DeleteContent, 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.

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.

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.