Gateway Events
All dispatch events are sent with opcode 0 (DISPATCH). The event name is in the t field and the event data is in the d field.
Receive Events
These events are dispatched from the gateway to your client.
READY
Sent after a successful IDENTIFY. Contains the initial session state.
- Name
session_id- Type
- string
- Description
The session ID for this connection.
- Name
user- Type
- User
- Description
The authenticated user object.
- Name
presences- Type
- array
- Description
Array of
{ user: User, status: string }for online friends/contacts.
- Name
warp_states- Type
- WarpStateObject[]
- Description
Array of
{ user_id, channel_id, session_id }for users currently warped into planets.
- Name
systems- Type
- System[]
- Description
Array of systems the user is a member of (minimal — full data comes via SYSTEM_CREATE).
- Name
equipment- Type
- Equipment?
- Description
The user's current equipment loadout, or null.
- Name
inventory- Type
- ItemInstance[]
- Description
The user's inventory items.
- Name
read_states- Type
- ReadState[]
- Description
Array of
{ user_id, channel_id, last_read_message_id, mention_count }for unread tracking.
SYSTEM_CREATE
Sent after READY for each system the user is a member of. Also sent when the user joins a new system.
- Name
...- Type
- System
- Description
All System fields (id, name, slug, flags, access, icon, banner, description, owner_id, etc.).
- Name
members- Type
- SystemMember[]
- Description
Array of system members.
- Name
member_count- Type
- integer
- Description
Total member count.
- Name
channels- Type
- Channel[]
- Description
Array of channels in this system.
- Name
channel_count- Type
- integer
- Description
Total channel count.
- Name
roles- Type
- SystemRole[]
- Description
Array of roles in this system.
- Name
presences- Type
- array
- Description
Array of
{ user_id, status }for online members.
- Name
warp_states- Type
- WarpStateObject[]
- Description
Array of warp states for members in planet channels.
SYSTEM_UPDATE
Sent when a system's properties are updated.
The d field contains a partial System object with only the changed fields, plus id.
SYSTEM_DELETE
Sent when a system is deleted or the user is removed from it.
- Name
id- Type
- string
- Description
The ID of the deleted system.
CHANNEL_CREATE
Sent after READY for each DM/group DM channel. Also sent when a new channel is created in a system.
The d field contains a full Channel object. For DM channels, includes recipients.
CHANNEL_UPDATE
Sent when a channel is updated. The d field contains a partial Channel object with changed fields plus id.
CHANNEL_DELETE
Sent when a channel is deleted.
- Name
id- Type
- string
- Description
The ID of the deleted channel.
MESSAGE_CREATE
Sent when a new message is created in any channel the user can see.
- Name
id- Type
- string
- Description
The message ID.
- Name
type- Type
- MessageType
- Description
The message type (0 = DEFAULT, 19 = REPLY, etc.).
- Name
content- Type
- string
- Description
The message content.
- Name
channel_id- Type
- string
- Description
The channel ID this message was sent in.
- Name
author- Type
- User
- Description
The user who sent the message.
- Name
message_reference- Type
- Message?
- Description
The referenced message, if this is a reply.
- Name
nonce- Type
- string?
- Description
Client-generated nonce for optimistic message matching.
- Name
flags- Type
- integer
- Description
Message flags bitfield.
- Name
created_at- Type
- string
- Description
ISO timestamp of creation.
- Name
edited_at- Type
- string?
- Description
ISO timestamp of last edit, if any.
MESSAGE_DELETE
Sent when a message is deleted.
- Name
id- Type
- string
- Description
The ID of the deleted message.
- Name
channel_id- Type
- string
- Description
The channel the message was in.
MESSAGE_ACK
Sent when a message is acknowledged (marked as read).
- Name
channel_id- Type
- string
- Description
The channel ID.
- Name
last_read_message_id- Type
- string
- Description
The ID of the last read message.
PRESENCE_UPDATE
Sent when a user's presence changes.
- Name
user- Type
- User
- Description
The user whose presence changed.
- Name
status- Type
- string
- Description
One of:
online,away,dnd,invisible,offline.
- Name
custom_status- Type
- string?
- Description
Custom status text, or null.
WARP_STATE_UPDATE
Sent when a user enters or leaves a planet channel.
- Name
user_id- Type
- string
- Description
The user who changed warp state.
- Name
channel_id- Type
- string?
- Description
The planet channel ID, or null if the user left.
- Name
session_id- Type
- string?
- Description
The session ID, or null if the user left.
WARP_SERVER_UPDATE
Sent in response to a WARP_STATE_UPDATE (op 5) with connection details for the voice/game server.
- Name
token- Type
- string
- Description
Auth token for the voice server.
- Name
channel_id- Type
- string
- Description
The planet channel ID.
- Name
endpoint- Type
- string
- Description
The voice server WebSocket URL.
- Name
session_id- Type
- string
- Description
The voice session ID.
RELATIONSHIP_UPDATE
Sent when a relationship with another user changes (friend request sent/accepted/removed, block, etc.).
The d field contains a Relationship object.
MESSAGE_REACTION_ADD
Sent when a reaction is added to a message.
- Name
user_id- Type
- string
- Description
The ID of the user who added the reaction.
- Name
channel_id- Type
- string
- Description
The channel the message is in.
- Name
message_id- Type
- string
- Description
The message that was reacted to.
- Name
emoji- Type
- string
- Description
The emoji that was used.
MESSAGE_REACTION_REMOVE
Sent when a reaction is removed from a message.
- Name
user_id- Type
- string
- Description
The ID of the user who removed the reaction.
- Name
channel_id- Type
- string
- Description
The channel the message is in.
- Name
message_id- Type
- string
- Description
The message that was unreacted to.
- Name
emoji- Type
- string
- Description
The emoji that was removed.
INVENTORY_UPDATE
Sent when an item in the user's inventory changes. The d field contains an ItemInstance object.
INVENTORY_DELETE
Sent when items are removed from the user's inventory.
- Name
instance_ids- Type
- string[]
- Description
Array of item instance IDs that were removed.
SYSTEM_ROLE_CREATE
Sent when a new role is created in a system.
- Name
system_id- Type
- string
- Description
The system the role was created in.
- Name
role- Type
- SystemRole
- Description
The created role object.
SYSTEM_ROLE_UPDATE
Sent when a role is updated. Same structure as SYSTEM_ROLE_CREATE.
- Name
system_id- Type
- string
- Description
The system the role belongs to.
- Name
role- Type
- SystemRole
- Description
The updated role object.
SYSTEM_ROLE_DELETE
Sent when a role is deleted.
- Name
system_id- Type
- string
- Description
The system the role belonged to.
- Name
role_id- Type
- string
- Description
The ID of the deleted role.
SYSTEM_MEMBER_ADD
Sent when a new member joins a system.
- Name
system_id- Type
- string
- Description
The system the member joined.
- Name
member- Type
- SystemMember
- Description
The member object.
SYSTEM_MEMBER_UPDATE
Sent when a member's properties change (nickname, roles, etc.).
- Name
system_id- Type
- string
- Description
The system the member belongs to.
- Name
member- Type
- SystemMember
- Description
The updated member object.
SYSTEM_MEMBER_REMOVE
Sent when a member leaves or is removed from a system.
- Name
system_id- Type
- string
- Description
The system the member left.
- Name
user_id- Type
- string
- Description
The ID of the removed user.
PLANET_SCANNED
Sent when a planet channel is scanned for the first time.
INVALID_SESSION
Sent when the current session is no longer valid. Reconnect and re-identify.
- Name
message- Type
- string
- Description
Description of why the session is invalid.
Send Events
These events are sent from your client to the gateway. See the Wormhole Gateway page for usage details.
| Event | Opcode | Description |
|---|---|---|
| IDENTIFY | 2 | Start a session with { token } |
| HEARTBEAT | 1 | Keep the connection alive |
| PRESENCE_UPDATE | 3 | Update status with { status, custom_status? } |
| WARP_STATE_UPDATE | 5 | Enter/leave a planet with { channel_id } |