Skip to main content

​
Overview

The MessagingClient is the Room API for participant-to-participant messages inside a room. Use it for direct JSON messages, room-wide broadcasts, and participant presence. If you need incremental or long-lived streaming, use streaming toolkits instead. Messaging stream APIs have been removed.

​
Why use the Messaging API?

  • Send structured JSON messages between room participants.
  • Broadcast announcements to everyone in a room.
  • Track which remote participants currently have messaging enabled.
  • Attach raw bytes to a normal message when needed.

​
Core concepts

​
Participant-based delivery

Messaging targets Participant objects. That gives you one delivery model for users, agents, and services in the same room.

​
Typed JSON payloads

Each message has a type plus a JSON payload. Use that to build chat flows, control messages, coordination events, or lightweight app protocols.

​
Optional binary attachments

Messages may include an attachment for cases where you need to send bytes along with the JSON body.

​
Streaming toolkits for streaming work

Messaging no longer exposes stream open/accept/chunk/close APIs. If your use case needs incremental results or chunked transfer, use a streaming toolkit instead of room.messaging.

​
Getting Started

# Suppose you already have a RoomClient instance named `room`

await room.messaging.enable()

participant = room.messaging.get_participant_by_name("other-user")
if participant is not None:
    await room.messaging.send_message(
        to=participant,
        type="chat",
        message={"text": "Hello from Python!"},
    )

await room.messaging.broadcast_message(
    type="announcement",
    message={"content": "Hello everyone!"},
)

​
API Methods

​
enable()

Enables messaging for the current participant and starts participant discovery for the messaging subsystem. 
await room.messaging.enable()

​
disable()

Disables messaging for the current participant. 
await room.messaging.disable()

​
sendMessage(…)

Sends a direct message to one participant. 
await room.messaging.send_message(
    to=participant,
    type="chat",
    message={"text": "Hey!"},
    attachment=b"\x01\x02\x03",
)

​
broadcastMessage(…)

Broadcasts a message to every participant with messaging enabled. 
await room.messaging.broadcast_message(
    type="announcement",
    message={"title": "Maintenance", "content": "We will be down tonight."},
)

​
remoteParticipants / getParticipants()

Returns the currently known remote participants with messaging enabled.

​
getParticipant(id) / getParticipantByName(name)

Looks up a known remote participant by id or by the name attribute.

​
Notes

  • Messaging is intended for discrete participant messages, not incremental response streams.
  • For streaming responses, chunked transfer, or bidirectional streaming, use a streaming toolkit.
  • Participant presence is only available after enable() completes.