User Presence

Endpoints:

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

Update from any Endpoint Call

A user's status can be updated on any authenticated call similarly to the update presence call:

  • Include the update_presence query parameter with a status for its value.
  • An optional update_presence_expiration parameter can be included to specify the expiration.

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.

Return presence Object Parameters

Field Type Description
avatar_image string URL linking to the current avatar image.
id string Primary identifier for the user that made the update.
last_seen_at string Optional time at which the presence was updated, in ISO 8601 format; YYYY-MM-DDTHH:MM:SSZ.
name string Optional user-supplied name. All Unicode characters allowed. Maximum length 50 characters. Be sure to escape if necessary.
presence string Updated user presence, up to 100 characters.
username string Username of the user that made the update. Case sensitive. 20 characters, may only contain a-z, 0-9 and underscore.

GET /presence

Token: user

Scope: any

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

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

Returns a list of users' presences.

{
    "meta": {
        "code": 200
    },
    "data": []
}

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/v1/users/1/presence" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "X-Pretty-Json: 1"

Returns a user's current presence.

{
    "meta": {
        "code": 200
    },
    "data": {
        "avatar_image": "String",
        "id": "0",
        "last_seen_at": "ISO 8601",
        "name": "String",
        "presence": "String",
        "username": "String"
    }
}

PUT /users/me/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.

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.
expiration Unix timestamp for when the given presence should expire. Default is 15 minutes into the future. If set too far into the future, will set to the maximum of 7 days. If set to a past timestamp, will delete the user's presence.
Example
curl "https://api.pnut.io/v1/users/me/presence" \
    -X PUT \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "presence=keeping my stick on the ice&expiration=1721702296" \
    -H "X-Pretty-Json: 1"

Returns the updated user presence.

{
    "meta": {
        "code": 200
    },
    "data": {
        "avatar_image": "String",
        "id": "0",
        "last_seen_at": "ISO 8601",
        "name": "String",
        "presence": "String",
        "username": "String"
    }
}