User Presence

A user's presence is the recent status of that user. Each updated presence lasts for 15 minutes, or until another status is given. Users who do not have a current status show up as "offline".

A user's status can be updated on any authenticated call by simply including the update_presence query parameter with a status for its value. If this method is attempted, the response's meta.updated_presence key will be set and true. If it fails to update, it will be false.

Endpoints:

GET /presence

Token: user

Scope: any

Retrieve all users' presence statuses that are not "offline".

Example
curl "https://api.pnut.io/v0/presence" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "X-Pretty-Json: 1"

Returns a list of users' presences.

"call for example 1"

GET /users/{user_id}/presence

Token: user

Scope: any

Retrieve a user's presence.

If the user has never set a presence, last_seen_at will not be set.

URL Parameters

Name Description
user_id ID of the user to retrieve
Example
curl "https://api.pnut.io/v0/users/1/presence" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "X-Pretty-Json: 1"

Returns a user's current presence.

"call for example 2"

PUT /users/{user_id}/presence

Token: user

Scope: presence

Update a user's presence.

If the update_presence query parameter is set on this call, it will override this call. It will not occur twice.

URL Parameters

Name Description
user_id ID of the user presence to update

PUT Parameters

Name Description
presence A string up to 100 unicode characters. If not set, or if it is set to 1, it will be updated to "online". A value of "offline" or 0 will delete the user's presence and remove them from the list of users online.
Example
curl "https://api.pnut.io/v0/users/me/presence" \
    -X PUT \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "presence=keeping my stick on the ice" \
    -H "X-Pretty-Json: 1"
"call for example 3"