The Messaging API keeps a realtime connection (powered by socket.io (opens in a new tab)) between your client and ProteusAI. This is how messages are sent with low latency and how agent replies are streamed back as they are generated.

The easiest way to use it is the Node SDK, which wraps this connection. The events below are the raw protocol if you connect with a socket.io client directly.

Connecting

Connect to the base URL and pass your token in the auth option.

import ProteusAI from '@proteus-ai/sdk';
const proteus = new ProteusAI({ apiKey: 'user-3a4d80a9c3cca7ffd1bc341f...' });
await proteus.connect(); // resolves once authenticated

Once the connection is authenticated, the server emits a success event. An invalid token results in an error event followed by a disconnect.

Client → server events

All client events use an acknowledgement callback that receives { data } on success or { error: { message } } on failure.

socket.emit('chat:join', { chatId: '682f4b313981b5f54e96ea4b' }, (res) => {
  if (res.error) console.error(res.error.message);
});
 
socket.emit(
  'message:send',
  { chatId: '682f4b313981b5f54e96ea4b', content: 'Hello!', type: 'TEXT' },
  (res) => console.log('sent', res.data?.message?.id)
);

Server → client events

Emitted to every client that has joined the relevant chat's room.

Streaming

When an agent streams a response, you receive a sequence of message:delta events sharing the same streamId, followed by a single message:done:

let buffer = '';
socket.on('message:delta', ({ contentDelta, content }) => {
  buffer += contentDelta ?? '';      // append the new chunk
  render(content);                    // `content` is the full text so far
});
socket.on('message:done', (message) => {
  console.log('final:', message.content);
});

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