Message Events

MessageEventsClient provides real-time WebSocket subscriptions for on-chain message events. Access it via client.messageEvents.

This is a live subscription, not a historical indexer. Use it for UI updates (e.g. "new message arrived") rather than replaying past messages.

Listening for incoming messages

const sub = client.messageEvents.listenIncoming({
  onMessage: async (message, event) => {
    console.log("new message in thread", event.threadId, "seq", event.msgSeq);
    const content = await message.loadContent();
    console.log(content.text);
  },
  onError: (err) => console.error(err),
});

// when done
await sub.stop();

---

Methods

client.messageEvents.listen(params)

Subscribe to all message events, with optional filters.

const sub = client.messageEvents.listen({
  threadId: 42,          // only this thread
  sender: senderKey,     // only from this sender
  receiver: receiverKey, // only to this receiver
  onMessage: async (message, event) => { ... },
  onError: (err) => { ... },
});

Returns PacketEventSubscription

---

client.messageEvents.listenIncoming(params)

Shorthand for listen({ incomingFor: client.walletPublicKey, ... }). Fires for all messages where the connected wallet is the receiver.

Returns PacketEventSubscription

---

client.messageEvents.listenOutgoing(params)

Shorthand for listen({ outgoingFrom: client.walletPublicKey, ... }). Fires for all messages sent by the connected wallet.

Returns PacketEventSubscription

---

client.messageEvents.listenThread(threadId, params)

Fires for every message in a specific thread.

const sub = client.messageEvents.listenThread(42, {
  onMessage: async (message, event) => { ... },
});

Returns PacketEventSubscription

---

ListenMessagesParams

Field	Type	Description
onMessage	(client: MessageClient, event: PacketMessageSentEvent) => void | Promise<void>	Called for each matching event
onError	(error: unknown) => void	Called if processing throws
threadId	number	Filter to a specific thread
sender	PublicKey	Filter by sender wallet
receiver	PublicKey	Filter by receiver wallet
incomingFor	PublicKey	Convenience: receiver must equal this key
outgoingFrom	PublicKey	Convenience: sender must equal this key

---

PacketMessageSentEvent

The event payload passed to onMessage:

type PacketMessageSentEvent = {
  threadId: number;
  msgSeq: number;
  sender: PublicKey;    // party who sent this message
  receiver: PublicKey;  // the other party
  slot: number;
  signature?: string;
};

---

PacketEventSubscription

Returned by all listen* methods:

type PacketEventSubscription = {
  id: number;
  stop: () => Promise<void>;
};

Call stop() to remove the WebSocket listener when you're done (e.g. on component unmount).