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:
Scope:
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:
Scope:
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:
Scope:
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"
}
}