Cord LogoDocs
Sign inStart now

Presence

Rest API /
Ask the Community

All available operations for user presence

Update a user's presence #

This endpoint updates a user's location.

HTTP Request #

HTTP:
PUT https://api.cord.com/v1/users/<USER_ID>/presence
cURL:
curl https://api.cord.com/v1/users/<USER_ID>/preferences \
  -X PUT \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
  -H 'Content-Type: application/json'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord user update-presence <USER_ID>
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.

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:
{
   "groupID": "<GROUP_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.
groupID
optional
string
The ID of the group which should be able to see this presence update
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:

JSON:
{
    "success": true,
    "message": "✅ You successfully updated user <USER_ID> presence"
}
              
{
    "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:
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" },
    "groupID": <GROUP_ID>
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord user update-presence <USER_ID>
--location='{ "page": "docs", "section": "presence" }'
--group-id=<GROUP_ID>
              
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" },
    "groupID": <GROUP_ID>
  }'
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy