Skip to content

Gateway🔗

The Gateway is Guilded's form of real-time communication over secure WebSockets. Clients will receive events and data over the gateway they are connected to and send data over the REST API. The API for interacting with Gateways is complex and fairly unforgiving, therefore it's highly recommended you read all of the following documentation before writing a custom implementation.

Payloads🔗

Gateway Payload Structure🔗

The only constant field you will receive is type - the event's name. Except when connecting, type will not be null; it will simply not be included.

The rest of the event's data is included top-level with the event payload (e.g. no data field which contains it all). For reference purposes, your typical Gateway payload will look something like this:

{
  "type": "EventName",
  "somethingId": "ffd717d5-73f1-11eb-8d50-6245b4f631c5",
  "listOfThings": [],
  "stackedContentObject": {
    "nodes": [{
      "leaves": [{
        "content": "hey go write something funny for the docs"
      }]
    }]
  },
  "happenedAt": "ISO8601.T.ime:sta:mpZ",
  "imageLink": "https://the-entire-url.to-the-file-on.aws/because_lol-Large.webp",
  "madeBy": "5A2B60"
}

Connecting to the Gateway🔗

It is important to note the Gateway's base URL here (which is different from the REST API's):

wss://api.guilded.gg

Connecting🔗

Gateway URL Params🔗
Field Type Description Accepted Values
jwt string authentication stuff? 'undefined'
EIO integer Engine.IO version 3
transport string the type of transport 'websocket'
guildedClientId string used for authentication the guilded_mid cookie received when logging in via REST
?teamId * string the team's socket to connect to a team ID

* This is for team-specific events like member and channel updates. In order to receive a team's events, you will need to open a separate connection for it, which you should treat just like the main websocket - heartbeat and all.

The first step in establishing connectivity to the gateway is to construct your gateway URL. Options are pretty limited, so you should end up with something like wss://api.guilded.gg/socket.io/?jwt=undefined&EIO=3&transport=websocket&guildedClientId={guilded_mid_header} (assuming you don't want to connect to a team websocket).

You can now open a websocket connection to the URL you have created.

Once connected, the client should immediately receive a "hello"-type payload, with information on the connection's heartbeat interval.

Example Gateway Hello🔗
{
  "sid": "your_session_id",
  "upgrades": [],
  "pingInterval": 25000,
  "pingTimeout": 5000
}

Heartbeating🔗

The client should now begin sending heartbeat payloads (the string '2') every pingInterval milliseconds, until the connection is eventually closed or terminated, from now until the end of time, or forever hold your peace. It is unknown whether Guilded will suddenly request you for a heartbeat, so documentation for this case is not available.

Example Gateway Heartbeat ACK🔗
"3"

Disconnections🔗

If the gateway ever issues a disconnect to your client, it will provide a close event code that you can use to properly handle the disconnection. A full list of these close codes can be found in the Response Codes documentation.

When you close the connection to the gateway with the close code 1000 or 1001, your session will be invalidated and your bot will appear offline. If you simply close the TCP connection, or use a different close code, the bot session will remain active and timeout after a few minutes. This can be useful for a reconnect, which will resume the previous session.

Todo

verify that above applies

Rate Limiting🔗

Info

This section is about Gateway rate limits, not HTTP API rate limits.

Currently unknown. See above.

Commands and Events🔗

Commands are requests made by a client over the gateway.

Gateway Commands🔗
name description
Heartbeat maintains an active gateway connection
Trigger Typing shows your typing indicator in a channel

Events are payloads sent over the gateway to a client that correspond to events in Guilded.

Gateway Events🔗

Info

The TeamSocketReconnected event may be misspelled.

Name Description
Hello defines the heartbeat
DMChatChannelCreated new dm channel created
ChatChannelBroadcastCall
ChatChannelBroadcastCallResponse
ChatChannelUpdated team channel was updated
ChatChannelTyping user began typing in a channel
ChatChannelHidden team channel was hidden
ChatChannelNicknameChanged
ChatMessageCreated message was sent
ChatMessageUpdated message was edited
ChatMessageDeleted message was deleted
ChatMessagesDeleted multiple messages were deleted at once
ChatMessageReactionAdded user reacted to a message
ChatMessageReactionDeleted user removed a reaction to a message
ChatPinnedMessageCreated message was pinned
ChatPinnedMessageDeleted message was unpinned
TemporalChannelCreated thread was created
TemporalChannelUsersAdded user was added to a thread
TeamSocketReconnected client reconnected to a team websocket
TeamRolesUpdated role was created/removed/edited in a team
TeamXpAdded
TeamXpSet
TeamReactionsUpdated
TeamContentReactionsAdded
TeamContentReactionsRemoved
TeamContentDeleted
TeamMessagesDeleted
TeamThreadCreated
TeamThreadReplyCreated
TeamEventModified
TeamEventCreated
TeamEventRemoved
TeamMemberJoined member joined a team
TeamMemberRemoved user removed from a team
TeamMembersRemoved user were pruned from a team
TeamMutedMembersUpdated member was muted or unmuted
TeamDeafenedMembersUpdated member was deafened or undeafened
TeamMemberAliasUpdated member's nickname was set or reset
TeamSubscriptionInfoUpdated probably something about guilded gold
TeamStreamInfoUpdated member started or stopped video streaming
TeamContentOperationsApplied
TeamContentReplaced
TeamContentReplyAdded
TeamContentReplyRemoved
TeamAvailabilitiesUpdated
TeamChannelAvailabilitiesUpdated
TeamChannelAvailabilitiesRemoved
TeamMemberUpdated member was updated
TeamMemberSocialLinkUpdated social media info for a team was updated
TeamGameAdded game was added to a team
TeamApplicationCreated user applied to join a team
TeamApplicationRemoved user's application was deleted (or denied?)
TeamApplicationUpdated user's application was updated
TeamUpdated team was updated
TeamChannelCreated new team channel was created
TeamChannelUpdated team channel was updated
TeamChannelPrioritiesUpdated team channel permissions (or position?) was updated
TeamChannelCategoryPrioritiesUpdated category permissions (or position?) was updated
TeamChannelDeleted team channel was deleted
TeamChannelsDeleted multiple team channels were deleted
TeamChannelCategoryCreated category was created
TeamChannelCategoryUpdated category was updated
TeamChannelCategoryDeleted category was deleted
TeamChannelCategoriesDeleted multiple categories were deleted
TeamChannelCategoryGroupMoved category position was changed
TeamWebhookCreated webhook was added to a team
TeamWebhookUpdated webhook was updated
TeamBotCreated flow-bot was added to a team
TeamBotUpdated flow-bot's info was updated
TeamBotFlowUpdated flow-bot's flow was updated
TeamGroupPrioritiesUpdated
TeamGroupDeleted group was deleted
TeamGroupArchived group was archived
TeamGroupRestored group was restored
TeamGroupFollowed user followed a group
TeamStripeAccountOnboarded
TeamServerSubscriptionPlanCreated
TeamServerSubscriptionPlanUpdated
TeamServerSubscriptionPlanDeleted
TeamServerSubscriptionUpdated
UserSocketConnected
UserSocketConnectError
UserSocketReconnected
UserSocketReconnecting
UserAliasUpdated
TeamMemberStreamUpdated
UserPresenceManuallySet
UserPresenceReceived
UserPinged
UserUpdated
UserTeamsUpdated
UserSocialLinkUpdated
UserTeamSectionUnreadCountIncremented
UserScannedMobileDownloadQr
UserStreamsVisibilityUpdated
TeamChannelContentCreated
TeamChannelContentCreatedSilent
TeamChannelContentReplyCreated
TeamChannelContentReplyUpdated
TeamChannelContentReplyDeleted
TeamChannelContentUpdated
TeamChannelContentDeleted
TeamChannelArchived
TeamChannelRestored
TeamChannelVoiceParticipantAdded
TeamChannelVoiceParticipantRemoved
TeamChannelVoiceUserClientConnected
TeamChannelStreamUserClientConnected
TeamChannelStreamAdded
TeamChannelStreamRemoved
TeamChannelStreamActive
TeamChannelStreamEnded
TeamChannelVoiceUserMoved
ChannelSeen client marked channel as read
ChannelContentSeen ^ ?
ChannelBadged
ChannelUnbadged
TeamGroupCreated
TeamGroupUpdated
TeamGroupDeletedForUser
TeamUserGroupPrioritiesUpdated
TeamGroupMarkedAsRead
MediaUploadProgress
VoiceChannelRegionPingReport

Event Names🔗

Event names are sent with each word capitalized and with no spaces/separators. For instance, Message Create would be ChatMessageCreated. Most of them are not exactly easily guessable, so the literal event name is preferred in this documentation for utility purposes.

Trigger Typing🔗

Begin "typing" in a specific channel. Send your payload as a string prefixed with "42". Like so:

42["ChatChannelTyping", {"channelId": "channelId"}]

Connecting🔗

Hello🔗

Sent on connection to the websocket. Defines the heartbeat interval that the client should heartbeat to.

Hello Structure🔗
Field Type Description
sid string your session's id
upgrades list possibly stuff like guilded gold that you've bought
pingInterval integer the interval (in milliseconds) the client should heartbeat with
pingTimeout integer how long (in milliseconds) guilded will wait without a heartbeat before disconnecting the client
Example Hello🔗
{
    "sid": "your_session_id",
    "upgrades": [],
    "pingInterval": 25000,
    "pingTimeout": 5000
}

Todo

fact check most stuff below

Channels🔗

DMChatChannelCreated🔗

Someone has created a new DM channel with you. Congrats! This is also sent when you create the channel, which is less exciting. You'll get a channel object in the payload.