diff --git a/docs/events/webhook-events.mdx b/docs/events/webhook-events.mdx index 9a597e782d..0bab602f5f 100644 --- a/docs/events/webhook-events.mdx +++ b/docs/events/webhook-events.mdx @@ -132,12 +132,18 @@ The table below includes the different webhook event types your app can subscrib The "Value" column corresponds to the event's `type` field value in the [event body object](/docs/events/webhook-events#event-body-object). -| Name | Value | Description | -|----------------------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------| -| [Application Authorized](/docs/events/webhook-events#application-authorized) | `APPLICATION_AUTHORIZED` | Sent when an app was authorized by a user to a server or their account | -| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user | -| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created | -| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) | +| Name | Value | Description | +|--------------------------------------------------------------------------------------|------------------------------|---------------------------------------------------------------------------| +| [Application Authorized](/docs/events/webhook-events#application-authorized) | `APPLICATION_AUTHORIZED` | Sent when an app was authorized by a user to a server or their account | +| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user | +| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created | +| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) | +| [Lobby Message Create](/docs/events/webhook-events#lobby-message-create) | `LOBBY_MESSAGE_CREATE` | Sent when a message is created in a lobby | +| [Lobby Message Update](/docs/events/webhook-events#lobby-message-update) | `LOBBY_MESSAGE_UPDATE` | Sent when a message is updated in a lobby | +| [Lobby Message Delete](/docs/events/webhook-events#lobby-message-delete) | `LOBBY_MESSAGE_DELETE` | Sent when a message is deleted from a lobby | +| [Game Direct Message Create](/docs/events/webhook-events#game-direct-message-create) | `GAME_DIRECT_MESSAGE_CREATE` | Sent when a direct message is created during an active Social SDK session | +| [Game Direct Message Update](/docs/events/webhook-events#game-direct-message-update) | `GAME_DIRECT_MESSAGE_UPDATE` | Sent when a direct message is updated during an active Social SDK session | +| [Game Direct Message Delete](/docs/events/webhook-events#game-direct-message-delete) | `GAME_DIRECT_MESSAGE_DELETE` | Sent when a direct message is deleted during an active Social SDK session | #### Application Authorized @@ -245,3 +251,262 @@ This event cannot be received by apps at this time. It's documented because it a ::: `QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord. + +#### Lobby Message Create + +`LOBBY_MESSAGE_CREATE` is sent when a message is created in a lobby. + +###### Lobby Message Create Structure + +The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object). + +###### Lobby Message Create Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "LOBBY_MESSAGE_CREATE", + "timestamp": "2024-10-18T18:41:21.109604", + "data": { + "id": "1397729799727878254", + "type": 0, + "content": "welcome to the party!", + "lobby_id": "1397729744753266719", + "channel_id": "1397729744753266719", + "author": { + // user data + }, + "flags": 65536, + "application_id": "1234567765431056709" + } + } +} +``` + +#### Lobby Message Update + +`LOBBY_MESSAGE_UPDATE` is sent when a message is updated in a lobby. + +###### Lobby Message Update Structure + +The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object) with additional fields for message updates. + +###### Lobby Message Update Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "LOBBY_MESSAGE_UPDATE", + "timestamp": "2025-08-05T20:39:19.587872", + "data": { + "id": "1402390388030832792", + "type": 0, + "content": "noice", + "lobby_id": "1402385687281537066", + "channel_id": "1402389638311841883", + "author": { + // user data + }, + "edited_timestamp": "2025-08-05T20:39:19.557970+00:00", + "flags": 0, + "timestamp": "2025-08-05T20:38:43.660000+00:00" + } + } +} +``` + +#### Lobby Message Delete + +`LOBBY_MESSAGE_DELETE` is sent when a message is deleted from a lobby. + +###### Lobby Message Delete Structure + +| Field | Type | Description | +|----------|-----------|-----------------------------------------------| +| id | snowflake | ID of the deleted message | +| lobby_id | snowflake | ID of the lobby where the message was deleted | + +###### Lobby Message Delete Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "LOBBY_MESSAGE_DELETE", + "timestamp": "2025-08-05T21:44:09.412957", + "data": { + "id": "1402406637632884857", + "lobby_id": "1402399883394285659" + } + } +} +``` + +#### Game Direct Message Create + +`GAME_DIRECT_MESSAGE_CREATE` is sent when a direct message is created while at least one user has an active Social SDK session. + +###### Game Direct Message Create Structure + +The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object). + +###### Game Direct Message Create Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "GAME_DIRECT_MESSAGE_CREATE", + "timestamp": "2025-08-14T18:09:38.063234", + "data": { + "id": "1405614357781545021", + "type": 0, + "content": "get in friend, we're going raiding", + "channel_id": "1405604229820715098", + "author": { + // user data + }, + "timestamp": "2025-08-14T18:09:37.947000+00:00", + "application_id": "1234567765431056709", + "attachments": [] + } + } +} +``` + +#### Game Direct Message Update + +`GAME_DIRECT_MESSAGE_UPDATE` is sent when a direct message is updated while at least one user has an active Social SDK session. + +###### Game Direct Message Update Structure + +The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object). + +###### Game Direct Message Update Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "GAME_DIRECT_MESSAGE_UPDATE", + "timestamp": "2025-08-14T16:44:31.847073", + "data": { + "id": "1405591838810706081", + "content": "almost ready to queue?", + "channel_id": "1404960877324533784", + "author": { + // user data + }, + "recipient_id": "1404960877324533784" + } + } +} +``` + +#### Game Direct Message Delete + +`GAME_DIRECT_MESSAGE_DELETE` is sent when a direct message is deleted while at least one user has an active Social SDK session. + +###### Game Direct Message Delete Structure + +The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object). + +###### Game Direct Message Delete Example + +```json +{ + "version": 1, + "application_id": "1234567765431056709", + "type": 1, + "event": { + "type": "GAME_DIRECT_MESSAGE_DELETE", + "timestamp": "2025-08-20T17:01:50.099204", + "data": { + "id": "1407771600643686503", + "type": 0, + "content": "cant make it in time", + "channel_id": "1405604229820715098", + "author": { + // user data + }, + "timestamp": "2025-08-20T17:01:44.725000+00:00", + "flags": 0, + "attachments": [], + "components": [] + } + } +} +``` + +## Social SDK Message Objects + +Discord Social SDK utilizes specialized message objects for lobby and direct message events that occur during active game sessions. These objects extend or modify the standard Discord message structure to support communication features. + +- [Lobby messages](/docs/events/webhook-events#lobby-message-object) include lobby-specific fields like `lobby_id` +- [Standard Discord messages](/docs/events/webhook-events#message-object) in SDK contexts may include additional fields +- [Passthrough messages](/docs/events/webhook-events#passthrough-message-object) are used for communication between provisional accounts + +These objects are used in the webhook events `LOBBY_MESSAGE_*` and `GAME_DIRECT_MESSAGE_*` depending on the messaging context. + +### Lobby Message Object + +Represents a message sent in a lobby or [Linked Channel](/docs/discord-social-sdk/development-guides/linked-channels). + +###### Lobby Message Structure + +| Field | Type | Description | +|-----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| id | snowflake | ID of the message | +| type | integer | [Type of message](/docs/resources/message#message-object-message-types) | +| content | string | Contents of the message | +| lobby_id | snowflake | ID of the lobby where the message was sent | +| channel_id | snowflake | ID of the channel the message was sent in | +| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message | +| metadata? | object | Additional metadata for the message (key-value pairs) | +| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | +| application_id? | snowflake | ID of the application (only present during active Social SDK sessions) | + +### Message Object + +Standard [Message Object](/docs/resources/message#messages-resource) with additional fields. + +###### Additional Fields + +| Field | Type | Description | +|-----------|----------------------------------------------------------|-----------------------------------------------------------------------------------------| +| lobby_id? | snowflake | ID of the lobby where the message was created (only present in Linked Channel messages) | +| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information | + +### Passthrough Message Object + +Represents a message between provisional users that exists only in-game. + +###### Passthrough Message Structure + +| Field | Type | Description | +|----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| id | snowflake | ID of the message | +| type | integer | [Type of message](/docs/resources/message#message-object-message-types) | +| content | string | Contents of the message | +| channel_id | snowflake | ID of the channel the message was sent in | +| recipient_id | snowflake | ID of the message recipient | +| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message | +| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | +| application_id | snowflake | ID of the application that created the message | +| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information | + +:::info +When both users in a direct message are provisional accounts, messages become "passthrough messages" that are only visible in-game and use this specialized structure. +:::