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:

Custom 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 The time at which the presence was update, 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.
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" \
    -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"
    }
}