Real-time connections

Choose the appropriate connection

The /agent namespace serves authenticated Inbox agents. The /widget namespace serves website visitors and starts with a visitor:connect event. Message Team uses its own /chat namespace. These are distinct protocols; a connection to one does not subscribe to the others.

For website installation, use the supplied widget bundle. For server integrations and AI agents, use the documented HTTP API or MCP connection rather than copying an agent session token into a website.

Connect an Inbox client

The agent connection requires a valid Message.com agent-session JWT. A Verify, iMessage or other product API key is not an agent JWT. Attach listeners before connecting.

import { io } from "socket.io-client";
const socket = io("https://app.message.com/agent", {
  auth: { token: agentSessionToken },
  transports: ["websocket", "polling"], autoConnect: false
});
socket.on("queue:snapshot", ({ conversations, truncated, total }) => {
  // Replace the displayed snapshot; do not append duplicates.
});
socket.on("connect", () => socket.emit("agent:hello"));
socket.on("connect_error", error => console.error(error.message));
socket.connect();

Reconnect and delivery

A connected socket is not a guarantee of uninterrupted delivery or a fixed latency. Rebuild the queue from queue:snapshot on reconnect and reload an open conversation with agent:open-conversation. Deduplicate messages by their server ID.

A server disconnect can indicate revoked access or an expired session. Resolve authentication or entitlement before manually reconnecting; do not loop indefinitely with the same rejected token.