Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
3.0 KB
Raw Blame

SPDX-License-Identifier: AGPL-3.0-or-later

title: Snowflakes description: The 64-bit IDs Fluxer gives every resource, how to get their creation time and how to send and page with them.

A snowflake is the 64-bit ID of a Fluxer resource, such as a user, guild, channel, message or role. The HTTP API, the Admin API and the Gateway all use the same IDs, and an ID is unique within the instance that issued it.

:::caution[Never parse a snowflake as a JSON number] Fluxer sends every snowflake as a string of decimal digits, because a JSON number can't represent one exactly. Parse the string into a 64-bit integer and compare snowflakes as integers. :::

Format

A snowflake packs a timestamp, a worker ID and a sequence into 64 bits. Bit 63 is always zero.

Field Bits Description
Timestamp 62 to 22 Milliseconds since the Fluxer epoch, 2015-01-01T00:00:00.000Z
Worker ID 21 to 12 The worker that issued the ID, from 0 through 1023
Sequence 11 to 0 A per-worker counter, from 0 through 4095

Every instance uses the same epoch. Don't rely on the worker ID or sequence.

Timestamps

To get the creation time in Unix milliseconds, shift the snowflake right by 22 bits and add the epoch. To build a cursor for a given time, reverse the calculation to get the smallest snowflake for that time.

timestamp_ms = (snowflake >> 22) + 1420070400000
snowflake = (timestamp_ms - 1420070400000) << 22

Snowflakes cover times from 2015-01-01T00:00:00.000Z through 2084-09-06T15:47:35.551Z.

A thread started from a message has that message's ID, so its timestamp is when the message was sent. The thread's own creation time is create_timestamp in its thread metadata.

Wire format

Send snowflakes as strings too. The HTTP API and the Gateway also accept a JSON integer.

Surface Accepts
HTTP request A string or JSON integer from 0 through 9223372036854775807, with no leading zero
Gateway command The same, except 0 is rejected

The HTTP API reports a malformed value as INVALID_SNOWFLAKE_FORMAT and a value that is too large as SNOWFLAKE_OUT_OF_RANGE.

Pagination

Snowflakes sorted as integers are in creation order, and list endpoints use them as cursors. A cursor doesn't have to be the ID of a real resource, and a snowflake built from a timestamp works too.

Cursor Selects
before IDs lower than the cursor
after IDs higher than the cursor
around A window centered on the cursor, including it

Only List channel messages and List messages from multiple channels accept around. Each endpoint lists the cursors it accepts, and a few endpoints use something other than a snowflake as the cursor.