Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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. If you need process-backed agent turn lifecycle such as turn.start, turn.started, turn.ended, steering, or interruption, see Agent Turns.

​
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.

​
Agent turns are a separate layer

Process-backed agents use room messaging as transport, but the turn protocol is a separate runtime concept. Use MessagingClient when you want:
  • participant-to-participant messages
  • broadcasts
  • attachments
  • participant discovery
Use Agent Turns when you want:
  • process-backed agent execution
  • turn lifecycle events
  • steering or interruption
  • thread-aware runtime control

​
CLI commands

Use meshagent room messaging when you want to inspect messaging-enabled participants or send one-off messages from the terminal:
bash
meshagent room messaging --help
meshagent room messaging list --room myroom
meshagent room messaging send \
  --room myroom \
  --to-participant-id PARTICIPANT_ID \
  --type chat \
  --data '{"text":"Hello from the CLI"}'
meshagent room messaging broadcast \
  --room myroom \
  --data '{"content":"Hello everyone"}'

​
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 process-backed agent turn lifecycle, see Agent Turns.
  • For streaming responses, chunked transfer, or bidirectional streaming, use a streaming toolkit.
  • Participant presence is only available after enable() completes.