Channel ABC

Channel

Channel(channel_id)

Bases: ABC

Base class for all channels.

trace_enabled property

trace_enabled

Whether any trace observers are registered.

provider_name property

provider_name

Provider or backend name for event attribution.

info property

info

Return channel metadata. Override in subclasses.

supports_streaming_delivery property

supports_streaming_delivery

Whether this channel can accept streaming text delivery.

on_trace

on_trace(callback, *, protocols=None)

Register a protocol trace observer.

Parameters:

Name	Type	Description	Default
callback	TraceCallback	Called with each :class:ProtocolTrace. May be sync or async (coroutines are scheduled as tasks).	required
protocols	list[str] | None	Optional allowlist of protocol names (e.g. ["sip"]). None means all protocols.	None

emit_trace

emit_trace(trace)

Emit a protocol trace to all registered observers.

resolve_trace_room

resolve_trace_room(session_id)

Resolve a room ID for a trace with the given session.

Override in session-based channels (voice, realtime voice) to map session IDs to room IDs. Returns None by default.

handle_inbound abstractmethod async

handle_inbound(message, context)

Process an inbound message into a RoomEvent.

deliver abstractmethod async

deliver(event, binding, context)

Deliver an event to this channel.

on_event async

on_event(event, binding, context)

React to an event. Default: no-op for transport channels.

deliver_stream async

deliver_stream(text_stream, event, binding, context)

Deliver a streaming text response to this channel.

Default: accumulate text, deliver as complete event.

connect_session async

connect_session(session, room_id, binding)

Accept a long-lived session after inbound processing.

Called by process_inbound when message.session is present and hooks did not block. Override in session-based channels (voice, persistent WebSocket, etc.). Default: no-op.

disconnect_session async

disconnect_session(session, room_id)

Clean up a session on remote disconnect.

Override in session-based channels to release resources. Default: no-op.

update_binding

update_binding(room_id, binding)

Notify the channel that a room's binding has changed.

Called by the framework after mute(), unmute(), or set_access() update the store. Override in session-based channels (voice, realtime voice) to update cached binding state used for audio gating. Default: no-op.

capabilities

capabilities()

Return channel capabilities.

close async

close()

Close the channel and its provider.

extract_text staticmethod

extract_text(event)

Extract plain text from an event's content.