Skip to content
OriginChats

User schema

A user object describes one account as other people see it. It appears in ready, users_list, presence events, and HTTP lookups.

{
  "username": "alice",
  "nickname": "Alice",
  "roles": ["moderator", "user"],
  "color": "#FFFF00",
  "cracked": false,
  "clients": ["mychat"],
  "devices": ["computer", "mobile"],
  "status": { "status": "online", "text": "Reviewing pull requests" }
}
type Presence = "online" | "idle" | "dnd" | "offline" | "invisible";


interface User {
  username: string;
  nickname?: string | null;
  roles: string[];
  color: string | null;
  cracked: boolean;
  clients: string[];
  devices: string[];
  bot?: true;
  pfp?: string;
  pfp_url?: string;
  status?: { status: Presence; text: string };
}
Field Description
username The account’s name, and the key to use in commands. Server accounts have the USR:local_ prefix.
nickname Display name, or null when none is set. For server accounts it’s the bare registered name. Use it for display only.
roles Role names, in the order stored on the account.
color The colour of the first role in roles that has one, or null. It can be "" when that role was created without a colour.
cracked true for a server account, false for a Rotur account.
clients Names of the apps the account is connected with right now. See below.
devices Kinds of device the account is connected from right now. See below.
bot true for a bot account. Left out for everyone else.
pfp, pfp_url Server accounts only: the avatar URL on this server. Both hold the same value.
status Presence and custom text, as this viewer is allowed to see it. Left out of HTTP responses.

Passwords, password hashes, and upload tokens never appear in a user object.

Bots

Section titled “Bots”

bot: true marks an account as a bot. The flag grants no permissions, and it’s separate from being a server account, a webhook, or a slash command provider. Servers that advertise user_metadata_v1 always send bot for bots, so a missing bot there means “not a bot”. On older servers, bot status is unknown.

Status

Section titled “Status”

status.status is one of online, idle, dnd, offline, or invisible. You see a user’s real status only if you are that user or hold manage_users. Everyone else sees:

  • offline with empty text while the user is invisible, offline, or has no connections.
  • online, idle, or dnd with the user’s text otherwise.

Clients and devices

Section titled “Clients and devices”

clients and devices describe the account’s open connections right now.

  • clients holds the client names that connections sent when they signed in, such as mychat. Connections that sent no valid name add nothing.
  • devices holds each connection’s device kind, such as computer or mobile. When a connection didn’t send one, the server may guess it from the WebSocket User-Agent.
  • Each list is sorted and has no duplicates. The two lists aren’t paired: clients[0] isn’t necessarily on devices[0].

Both lists are empty when:

  • The user has no open connections.
  • The user is invisible or offline, unless you are that user or hold manage_users.
  • The object comes from an HTTP route such as GET /user/{username}.

So empty lists don’t prove a user is offline. The lists are hints, not verified identities.

A full user object replaces both lists. A user_clients event replaces only these two lists for one user. Other partial updates leave them alone. auth lists the allowed client and device names.

See also

Section titled “See also”