Per-Channel User Presence

Endpoints:

A user's presence can be set for a specific channel, separately from its global User Presence. It functions identically, but there are no helpers for updating status from other endpoints.

Getting users subscribed to a channel with ?include_presence=1 query parameter will include the users' channel presence on their user object instead of their global presence.

GET /channels/{channel_id}/presence

Token: user

Scope: messages

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

Example
curl "https://api.pnut.io/v1/channels/582/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/channels/{channel_id}

Token: user

Scope: messages

Retrieve a user's presence in a channel.

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
channel_id ID of the channel to check within
Example
curl "https://api.pnut.io/v1/users/1/presence/channels/582" \
    -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 (Optional)",
        "name": "String (Optional)",
        "presence": "String",
        "username": "String"
    }
}

PUT /users/me/presence/channels/{channel_id}

Token: user

Scope: messages

Update a user's presence in a channel.

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/channels/582" \
    -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 (Optional)",
        "name": "String (Optional)",
        "presence": "String",
        "username": "String"
    }
}