Presence API

Endpoints for presence tracking, user search, and AI integration in chat rooms.

Overview

Presence tracking keeps track of which users are currently active in which rooms. The AI endpoint allows users to get AI-generated responses within chat rooms.

Endpoint Summary

Presence

Switch Rooms

Update presence when a user switches between rooms. This is used for real-time "who's online" functionality.

POST /api/presence/switch
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "previousRoomId": "general",
  "nextRoomId": "random",
  "username": "alice"
}

{
  "success": true
}

• User opens chat app → previousRoomId: null, nextRoomId: "general"

• User switches rooms → previousRoomId: "general", nextRoomId: "random"
• User closes chat app → previousRoomId: "random", nextRoomId: null

Global Presence Heartbeat

Track which users are globally online (independent of any specific room). Both methods require authentication.

POST /api/presence/heartbeat
Authorization: Bearer {token}
X-Username: alice

{
  "success": true
}

GET /api/presence/heartbeat
Authorization: Bearer {token}
X-Username: alice

{
  "users": ["alice", "bob"]
}

User Search

Search Users

Search for users by username prefix.

GET /api/users?search=ali
Authorization: Bearer {token}
X-Username: alice

Requires a valid Authorization token and X-Username pair. User search is rate-limited per authenticated user and can return 429 when the search bucket is exhausted.

{
  "users": [
    {
      "username": "alice",
      "lastActive": 1704067200000
    },
    {
      "username": "alicia",
      "lastActive": 1704000000000
    }
  ]
}

AI Integration

Ryo Reply

Generate an AI response from Ryo within a chat room. This is triggered when users mention @ryo in their messages.

POST /api/ai/ryo-reply
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "roomId": "general",
  "prompt": "what's up?",
  "systemState": {
    "chatRoomContext": {
      "recentMessages": "alice: hey everyone\nbob: hi alice\nalice: @ryo what's up?",
      "mentionedMessage": "@ryo what's up?"
    }
  }
}

{
  "message": {
    "id": "msg_123",
    "roomId": "general",
    "username": "ryo",
    "content": "hey, what's up",
    "timestamp": 1704067320000
  }
}

Rate Limits

AI Behavior

When mentioned in chat rooms, Ryo:

• Considers recent chat context

• Responds in a casual, friendly tone
• Can answer questions, provide information, or just chat
• Respects the room's conversation flow

Realtime Authorization

ryOS supports two realtime providers. The active provider is set by REALTIME_PROVIDER; each authorization endpoint only works for its matching provider (the other returns 400).

Pusher Channel Auth

Authorizes a subscription to an authorization-requiring Pusher channel (private-…, presence-…). The server verifies the authenticated user may access the requested channel before signing. Used with the Pusher provider.

POST /api/pusher/auth
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "socket_id": "123.456",
  "channel_name": "private-sync-alice"
}

Realtime Ticket (Local Provider)

Mints a short-lived, single-use ticket for authenticating a self-hosted WebSocket connection. The HttpOnly auth cookie is scoped to /api and unreadable from JS, so the WebSocket (on a different path) presents this ticket instead. Only relevant for the local realtime provider.

POST /api/realtime/ticket
Authorization: Bearer {token}
X-Username: alice

{
  "ticket": "..."
}

Real-time Updates

Presence changes and AI replies trigger Pusher broadcasts to connected clients:

Error Responses

Related

• Rooms API - Room endpoints

• Messages API - Message endpoints
• Chat API - Main AI chat endpoint (different from room @mentions)
• AI System - AI providers and capabilities