Messages

The messages API (proteus.messages) sends messages and receives replies — including streamed responses — over the realtime connection.

Sending messages

Send with a chatId, or with a chatKey + recipients to start/locate a chat. You can also pass a string for a quick TEXT message.

const { message, chatId } = await proteus.messages.send({
  chatId: '<chatId>',
  content: 'Hello, ProteusAI!',
  type: 'TEXT',
});

For a known chat, proteus.chats.send(chatId, payload) is a convenient wrapper.

The value returned by send is your outgoing message (now persisted with an id) — not the agent's reply. Replies arrive asynchronously through the listeners below.

const { message } = await proteus.messages.send({ chatId: '<chatId>', content: 'Hi' });
console.log(`ProteusAI ID for this message is ${message.id}`);

NOTE: Ensure the connection is established before sending. Either await proteus.connect() first, or send inside proteus.connected(() => { ... }):

proteus.connected(() => {
  proteus.messages.send({ chatId: '<chatId>', content: 'Hello, ProteusAI!' });
});

Listening for replies

Every listener returns an unsubscribe function.

// complete messages added to any joined chat
const off = proteus.messages.onMessage((message) => {
  console.log(`message ${message.id}: ${message.content}`);
});
 
// later, stop listening
off();

To scope listening to a single chat, use proteus.chats.on.

Message streaming

Agent responses can be streamed: you receive a sequence of delta chunks followed by a final done message. Inspect contentDelta for the new chunk and content for the text generated so far.

proteus.messages.onDelta(({ contentDelta, content, streamId }) => {
  // contentDelta -> the new chunk
  // content      -> the message so far
  // streamId     -> groups chunks of the same response
  process.stdout.write(contentDelta ?? '');
});
 
proteus.messages.onDone((message) => {
  console.log('\nThis complete message is:', message.content);
});

A reply that is not streamed arrives as a single onMessage event instead.

Low-level events

proteus.messages.on(event, callback) subscribes to any realtime event emitted to your joined chats (e.g. 'CHAT_STATE_UPDATED'). It returns an unsubscribe function. See Realtime for the full list of events.

const off = proteus.messages.on('CHAT_STATE_UPDATED', (evt) => console.log(evt));