Sign in
Room

Set ephemeral presence

Changed on

This endpoint sets ephemeral presence for a user in a room without requiring a WebSocket connection. The presence data will automatically expire after the specified TTL (time-to-live). This is useful for scenarios like showing an AI agent's presence in a room. The presence will be broadcast to all connected users in the room. Corresponds to liveblocks.setPresence.

post/rooms/{roomId}/presence

Request

  • Base URL: https://api.liveblocks.io/v2
  • URL: https://api.liveblocks.io/v2/rooms/{roomId}/presence
  • Auth: none declared

Path parameters

roomIdstring required

ID of the room

Example:my-room-id

Request body

userIdstring required

ID of the user to set presence for

dataobject required

Presence data as a JSON object

ttlinteger

Time-to-live in seconds (minimum: 2, maximum: 3599). After this duration, the presence will automatically expire.

Example request

{
  "userId": "agent-123",
  "data": {
    "status": "active",
    "cursor": {
      "x": 100,
      "y": 200
    }
  },
  "userInfo": {
    "name": "AI Assistant",
    "avatar": "https://example.org/images/agent123.jpg"
  },
  "ttl": 60
}

Response

Success. Presence was set for the user in the room.

Changes

  • 22a5e987b8c9Revision changes
    • breaking

      the request property became required

  • 77cd6a75b2b7Revision changes
    • breaking

      the / request property format changed from no format to uri

    • info

      api operation id post-rooms-roomId-presence removed and replaced with set-presence