Real-time Events

Subscribe to live events via Server-Sent Events (SSE) — messages, member activity, voice state, and more.

Connecting to the Event Stream

Open a persistent HTTP connection to the SSE endpoint. Events will be pushed to you in real time:

GET /api/bot/IEvents/v1/Stream?intents={bitmask}

Headers:
  Authorization: Bot YOUR_TOKEN
  Accept: text/event-stream
Parameter Type Description
intents number Bitmask of event categories to receive. Defaults to all non-privileged intents if omitted.
lastEventId string Resume from a previous event ID. Can also be sent as the Last-Event-ID header.

Intents

Intents are a bitmask that controls which events you receive. Combine flags with bitwise OR. For example, intents=5 subscribes to Messages (1) + Channels (4).

Intent Bit Value Events
Messages 0 1 MessageCreate, MessageDelete, MessageUpdate
Members (privileged) 1 2 MemberJoin, MemberLeave, MemberUpdate
Channels 2 4 ChannelCreate, ChannelDelete, ChannelUpdate
Reactions 3 8
Typing 4 16 TypingStart, TypingStop
Presence (privileged) 5 32 PresenceUpdate
Commands 6 64 CommandInteraction
DirectMessages 7 128 DirectMessageCreate
Moderation 8 256 MemberBanned, MemberKicked
Archetypes 9 512 ArchetypeChanged, ArchetypeCreated
SpaceUpdates 10 1024 SpaceModified
Voice 11 2048 VoiceJoin, VoiceLeave, VoiceMute, VoiceStreamStart, VoiceStreamStop, VoiceUnmute
Calls (privileged) 12 4096 CallEnded, CallIncoming

Privileged intents (Members, Presence) require your bot to be verified. Requesting privileged intents without verification will result in an error.

Common combinations
// Messages + Commands + Voice
intents = 1 | 64 | 2048 = 2113

// All non-privileged (default)
intents = 4061

// Everything (requires verification)
intents = 8191

Event Format

Events follow the standard SSE specification. Each event has id, event, and data fields:

id: 42
event: MessageCreate
data: {"id":"42","type":"MessageCreate","spaceId":"...","channelId":"...","data":{"messageId":12345,"text":"Hello!","creatorId":"..."}}

The data field is a JSON object with this structure:

{
  "id":        "42",               // sequential event ID
  "type":      "MessageCreate",    // event type enum
  "spaceId":   "...",              // space UUID (if applicable)
  "channelId": "...",              // channel UUID (if applicable)
  "data":      { ... }             // event-specific payload
}

Connection Lifecycle

When you connect, the server sends events in this order:

1

Ready

Sent immediately. Contains your active intents and the list of space IDs the bot belongs to.

{
  "id": "0", "type": "Ready",
  "data": { "intents": 4045, "spaceIds": ["uuid-1", "uuid-2"] }
}
2

Live Events

Events matching your intents are pushed as they occur.

3

Heartbeat

A Heartbeat event is sent every 30 seconds to keep the connection alive.

Reconnection & Replay

If your connection drops, you can resume without missing events. The server maintains a ring buffer of the last 500 events per bot.

To resume, pass the last event ID you received:

Option 1: Query parameter
GET /api/bot/IEvents/v1/Stream?intents=4045&lastEventId=42

Option 2: Standard SSE header
Last-Event-ID: 42

The server will replay missed events, then send a Resumed event with the count of replayed events before switching to live:

// Replayed events arrive first...
{ "id": "43", "type": "MessageCreate", "data": { ... } }
{ "id": "44", "type": "MemberJoin", "data": { ... } }

// Then the Resumed marker
{ "id": "resumed", "type": "Resumed", "data": { "replayed": 2 } }

// Then live events continue

Code Examples

TypeScript (Bun / Node.js)

import EventSource from "eventsource";

const es = new EventSource(
  "https://api.argon.gl/api/bot/IEvents/v1/Stream?intents=2113",
  { headers: { "Authorization": "Bot YOUR_TOKEN" } }
);

es.addEventListener("Ready", (e) => {
  const data = JSON.parse(e.data);
  console.log("Connected, spaces:", data.data.spaceIds);
});

es.addEventListener("MessageCreate", (e) => {
  const data = JSON.parse(e.data);
  console.log(`[${data.channelId}] ${data.data.text}`);
});

es.addEventListener("Heartbeat", () => {
  // Connection is alive
});

es.onerror = () => {
  // EventSource auto-reconnects with Last-Event-ID
};

C# (.NET)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bot YOUR_TOKEN");

using var stream = await client.GetStreamAsync(
    "https://api.argon.gl/api/bot/IEvents/v1/Stream?intents=2113");
using var reader = new StreamReader(stream);

string? eventType = null;
while (await reader.ReadLineAsync() is { } line)
{
    if (line.StartsWith("event: "))
        eventType = line[7..];
    else if (line.StartsWith("data: "))
    {
        var payload = JsonDocument.Parse(line[6..]);
        Console.WriteLine($"[{eventType}] {payload.RootElement}");
    }
}

All Event Types

Event Type Intent Description
Connection
Ready Sent on connection. Contains active intents and space IDs.
Heartbeat Keep-alive ping, sent every 30 seconds.
Resumed Sent after replaying missed events on reconnection.
Messages
MessageCreate Messages A new message was sent in a channel.
MessageUpdate Messages A message was edited.
MessageDelete Messages A message was deleted.
Members
MemberJoin Members A user joined a space.
MemberLeave Members A user left a space.
MemberUpdate Members A member's profile or roles changed.
Channels
ChannelCreate Channels A new channel was created.
ChannelUpdate Channels A channel's settings were modified.
ChannelDelete Channels A channel was deleted.
Typing
TypingStart Typing A user started typing in a channel.
TypingStop Typing A user stopped typing.
Presence
PresenceUpdate Presence A user's online status or activity changed.
Commands
CommandInteraction Commands A user invoked a slash command registered by the bot.
DirectMessages
DirectMessageCreate DirectMessages A direct message was sent to the bot.
Moderation
MemberKicked Moderation A member was kicked from a space.
MemberBanned Moderation A member was banned from a space.
Archetypes
ArchetypeChanged Archetypes An archetype (role) was modified.
ArchetypeCreated Archetypes A new archetype (role) was created.
SpaceUpdates
SpaceModified SpaceUpdates Space settings or details were updated.
Voice
VoiceJoin Voice A user joined a voice channel.
VoiceLeave Voice A user left a voice channel.
VoiceMute Voice A user muted themselves in a voice channel.
VoiceUnmute Voice A user unmuted themselves in a voice channel.
VoiceStreamStart Voice A user started streaming (screen share or camera).
VoiceStreamStop Voice A user stopped streaming.
Calls
CallIncoming Calls An incoming call is ringing for the bot.
CallEnded Calls A call the bot was involved in has ended.

Next Steps