Presence

All available operations for user presence

Update a user's presence #

This endpoint updates a user's location.

HTTP Request #

PUT https://api.cord.com/v1/users/<USER_ID>/presence

Copy

Request Body #

Listed below are the fields of the request body to be added as part of the HTTP PUT request.

organizationID

required

string

The organization that the user belongs to.

exclusiveWithin

optional

Location

Sets an "exclusivity region" for the ephemeral presence set by this update. A user can only be present at one location for a given value of exclusiveWithin. If the user becomes present at a different location with the same value of exclusiveWithin, they automatically become no longer present at all other locations with that value of exclusive_within. This is useful to more easily track presence as a user moves among sub-locations. For example, suppose we'd like to track which specific paragraph on a page a user is present. We could make those updates like this:

{
   "organizationID": "<ORG_ID>",
   "location": { "page": "<PAGE_ID>", "paragraph": "<PARAGRAPH_ID>" },
   "exclusiveWithin": { "page": "<PAGE_ID>" }
}

As a user moves around a page, their paragraphID will change, while their pageID will remain the same. The above call to setPresent will mark them present at their specific paragraph. However, since every update uses the same exclusiveWithin, each time they are marked present at one paragraph they will become no longer present at their previous paragraph.

location

required

Location

The location you want the user to be in.

durable

optional

boolean

When true, this is a durable presence update, when false, or is not used, it is an ephemeral presence update.

This value defaults to false.

absent

optional

boolean

When true, this is an absence update, meaning that the user has just left this location. If the user is currently present at that location, it is cleared. This cannot be used with a durable presence update.

This value defaults to false. The user will be set as present at the location.

Response #

If successful, the response will be:

{
    "success": true,
    "message": "✅ You successfully updated user <USER_ID> presence"
}

Copy

Example Request #

To show a user as present at the location { "page": "docs", "section": "presence" }.

curl "https://api.cord.com/v1/users/<USER_ID>/presence" \
  -X PUT \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": { "page": "docs", "section": "presence" },
    "organizationID": <ORG_ID>
  }'

Copy

Ask Cordy