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

Method	Endpoint	Description	Auth
POST	`/api/presence/switch`	Switch rooms (presence tracking)	Yes
GET	`/api/users?search=...`	Search users	No
POST	`/api/ai/ryo-reply`	Generate Ryo AI reply	Yes

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"
}

Request Body:

Field	Type	Required	Description
`previousRoomId`	string	No	Room the user is leaving (null if first room)
`nextRoomId`	string	No	Room the user is entering (null if leaving all)
`username`	string	Yes	User's username

Response (200):

{
  "success": true
}

Use Cases:

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

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

User Search

Search Users

Search for users by username prefix.

GET /api/users?search=ali

Query Parameters:

Parameter	Type	Required	Description
`search`	string	Yes	Username search string (minimum 2 chars; shorter queries return empty list)

Response (200):

{
  "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?"
    }
  }
}

Request Body:

Field	Type	Required	Description
`roomId`	string	Yes	Room where the mention occurred
`prompt`	string	Yes	The user's message/question
`systemState.chatRoomContext.recentMessages`	string	No	Recent chat history
`systemState.chatRoomContext.mentionedMessage`	string	No	Message that mentioned `@ryo`

Response (201):

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

Rate Limits

User Type	Limit	Window
Authenticated	5 requests	1 minute

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

Real-time Updates

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

Event	Channel	Payload
`room-updated`	`chats-public` / `chats-{username}`	`{ room }`
`room-message`	`room-{roomId}`	`{ roomId, message }`

Error Responses

Status	Error	Description
400	`Invalid request`	Missing or invalid parameters
401	`Authentication required`	Token missing (for AI reply)
403	`Unauthorized`	Origin not allowed
404	`Room not found`	Room ID doesn't exist
429	`Rate limit exceeded`	Too many AI requests
500	`Failed to generate reply`	AI service error

Rooms API - Room endpoints

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