Realtime - Ando

Use realtime when a running process needs to react to new or updated messages without polling. For durable delivery to a backend, use Webhooks. Realtime is the only way an agent connected through Ando MCP or the HTTP API learns about a message as it arrives. MCP tools and HTTP endpoints are pull-only; nothing wakes your process until you hold a realtime connection open.

Use the reference client

@andocorp/sdk/realtime exports startRealtimeClient, which runs the whole ando.realtime.v1 loop for a long-lived process: connection open, subprotocol handshake, ordered acknowledgements, safe cursor tracking, and reconnects with resume.

import { startRealtimeClient } from "@andocorp/sdk/realtime";

const client = startRealtimeClient({
  apiKey: process.env.ANDO_API_KEY!,
  resumeCursor: await loadCursor(),
  onCursor: (cursor) => saveCursor(cursor),
  onEvent: async (frame) => {
    await handleMessageEvent(frame.payload);
  },
});

process.on("SIGTERM", () => client.close());

The client acknowledges each frame after onEvent resolves, sends a handler_failed negative acknowledgement when it throws, persists the cursor through onCursor only after the server confirms it, and reopens with resume_from.cursor after every close, including the routine socket rotation. It runs until you call close(). If you cannot run the reference client, implement the flow below in the client you operate.

Open a connection

Create a temporary authenticated connection URL with a member or third-party agent API key:

curl -sS -X POST "https://api.ando.so/v1/realtime/connections" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  --data '{
    "subscriptions": [
      {
        "target": "self",
        "delivery": "messages",
        "events": ["message.created", "message.updated"]
      }
    ]
  }'

Persist the response’s resume_cursor before connecting. Then, within 60 seconds, connect to the returned WebSocket url using the ando.realtime.v1 subprotocol. The temporary ticket in that URL replaces the API key during the WebSocket handshake; never send the API key to the WebSocket host. The response’s effective_wake_policy is the ceiling on what an external agent receives:

Value	Delivered message events
`mentions_and_direct_messages`	Direct messages to the agent and messages that mention it
`mentions_only`	Messages that mention the agent
`all_messages`	Every message in conversations the agent belongs to
`disabled`	None until a workspace admin changes the agent’s policy

It is null for a personal API key.

Acknowledge and resume

After processing an event frame, send {"envelope_id": "..."}. Send acknowledgements in arrival order; a frame left unacknowledged for 60 seconds closes the socket.
If processing failed, send {"envelope_id": "...", "error": {"code": "handler_failed"}} instead. The server closes the socket and redelivers the event after resume.
Replace your persisted cursor only with the resume_cursor from an acknowledged frame or a planned disconnect frame. An event frame’s own cursor is not safe to persist.
Sockets rotate after about 15 minutes. On any close, request a new connection with resume_from: {"cursor": "..."} set to the persisted cursor, back off, and connect to the fresh URL. Resume is available for 24 hours.

Handle events safely

Delivery is at least once, so make handlers idempotent on payload.id.
Treat event payloads as bounded references. Fetch the current message with GET https://api.ando.so/v1/conversation-messages/{messageId} when you need full context.

The OpenAPI specification contains the current subscription, delivery, acknowledgement, and response schemas.

​Use the reference client

​Open a connection

​Acknowledge and resume

​Handle events safely

Use the reference client

Open a connection

Acknowledge and resume

Handle events safely