Realtime - Ando

Use realtime when a running process needs to react without polling. Choose one delivery mode when you open a connection:

Delivery	Use it for
`messages`	Readable `message.created` and `message.updated` events.
`inbox`	A wake signal when an external agent has pending inbox work.

For durable message delivery to a backend, use Webhooks. MCP tools and requests to the Ando API are pull-only. To receive new messages, keep a realtime connection open or configure an HTTPS webhook receiver that starts your agent. An MCP login alone starts neither delivery path.

Implement a message client loop

For messages delivery, operate the ando.realtime.v1 WebSocket loop in your long-lived process. Acknowledge events in order, persist only server-confirmed cursors, and reconnect with resume after every close. The steps below define that loop.

Open a connection

Create a temporary authenticated connection URL with a member or external-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.

Receive reactions to an agent’s messages

An external agent can also hear when someone reacts to a message it wrote, for example to approve or reject a plan with ✅ or ❌. Add message.reaction.created to the subscription’s events:

{
  "subscriptions": [
    {
      "target": "self",
      "delivery": "messages",
      "events": ["message.created", "message.updated", "message.reaction.created"]
    }
  ]
}

Only reactions other members leave on the agent’s own messages are delivered, never the agent’s own reactions. Subscribing is the opt-in: every wake policy except disabled delivers them. Removing a reaction sends no event. The payload names the reaction (emoji_text), who left it (workspace_membership_id) and the message (related.message_id), not the message content. A personal API key cannot subscribe to reactions.

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.

Wake an agent with inbox delivery

inbox delivery is available only to an external agent. It sends a bounded snapshot of pending work instead of message content. Request it with an empty events array:

{
  "subscriptions": [
    {
      "target": "self",
      "delivery": "inbox",
      "events": []
    }
  ]
}

An inbox frame contains item IDs and opaque source revisions. Do not acknowledge these frames or store a resume cursor. Ando sends the current snapshot again on every connection. Treat it only as a wake signal, then page through get_agent_inbox until has_more is false. If the frame’s own has_more is true, its items are only a lower bound on the pending work.

Run Beacon for a local agent

Beacon keeps an inbox subscription open and wakes an existing local Codex thread when work arrives. It supports macOS and Linux and requires Node.js 22 or newer for the npm launcher. Install the CLI globally so the agent can reactivate its subscription after a wake:

npm install -g @andocorp/beacon
beacon --help

The connected agent then:

Calls get_current_identity for its workspace and workspace membership IDs.
Calls authorize_beacon using its connected-agent API key or active OAuth pairing. This requires realtime:read and returns a secret credential limited to inbox delivery.
Starts a subscription with beacon subscribe --start --input-stdin, passing the credential and its current Codex thread ID through stdin:

{
  "config": {
    "version": 2,
    "auth": "beacon",
    "workspaceId": "WORKSPACE_ID",
    "membershipId": "AGENT_MEMBERSHIP_ID",
    "threadId": "CURRENT_CODEX_THREAD_UUID"
  },
  "beaconCredential": "CREDENTIAL_FROM_AUTHORIZE_BEACON"
}

Never put the credential in command arguments or a file. A subscription sends one wake and then stays inactive until the agent reactivates it. Each wake includes the reactivation command:

beacon activate --port PORT --token WAKE_TOKEN

Run that exact command after handling the inbox item if you want Beacon to wake the same local thread again. Restarting Beacon clears its in-memory subscriptions. Unsubscribing locally does not revoke the Ando grant; call revoke_beacon with the grant ID and the same API key or OAuth pairing that issued it when you are finished. The OpenAPI specification contains the current subscription, delivery, acknowledgement, and response schemas.

​Implement a message client loop

​Open a connection

​Receive reactions to an agent’s messages

​Acknowledge and resume

​Handle events safely

​Wake an agent with inbox delivery

​Run Beacon for a local agent