Skip to content

Commit 2c539c6

Browse files
meka-ddevmeka-ddev
authored
Social SDK webhook events doc update (#7822)
* adding new Social SDK webhook events
1 parent fc88373 commit 2c539c6

File tree

1 file changed

+271
-6
lines changed

1 file changed

+271
-6
lines changed

‎docs/events/webhook-events.mdx‎

Lines changed: 271 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -132,12 +132,18 @@ The table below includes the different webhook event types your app can subscrib
132132

133133
The "Value" column corresponds to the event's `type` field value in the [event body object](/docs/events/webhook-events#event-body-object).
134134

135-
| Name | Value | Description |
136-
|----------------------------------------------------------------------------------|----------------------------|------------------------------------------------------------------------|
137-
| [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 |
138-
| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user |
139-
| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created |
140-
| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) |
135+
| Name | Value | Description |
136+
|--------------------------------------------------------------------------------------|------------------------------|---------------------------------------------------------------------------|
137+
| [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 |
138+
| [Application Deauthorized](/docs/events/webhook-events#application-deauthorized) | `APPLICATION_DEAUTHORIZED` | Sent when an app was deauthorized by a user |
139+
| [Entitlement Create](/docs/events/webhook-events#entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created |
140+
| [Quest User Enrollment](/docs/events/webhook-events#quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) |
141+
| [Lobby Message Create](/docs/events/webhook-events#lobby-message-create) | `LOBBY_MESSAGE_CREATE` | Sent when a message is created in a lobby |
142+
| [Lobby Message Update](/docs/events/webhook-events#lobby-message-update) | `LOBBY_MESSAGE_UPDATE` | Sent when a message is updated in a lobby |
143+
| [Lobby Message Delete](/docs/events/webhook-events#lobby-message-delete) | `LOBBY_MESSAGE_DELETE` | Sent when a message is deleted from a lobby |
144+
| [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 |
145+
| [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 |
146+
| [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 |
141147

142148
#### Application Authorized
143149

@@ -245,3 +251,262 @@ This event cannot be received by apps at this time. It's documented because it a
245251
:::
246252

247253
`QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord.
254+
255+
#### Lobby Message Create
256+
257+
`LOBBY_MESSAGE_CREATE` is sent when a message is created in a lobby.
258+
259+
###### Lobby Message Create Structure
260+
261+
The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object).
262+
263+
###### Lobby Message Create Example
264+
265+
```json
266+
{
267+
"version": 1,
268+
"application_id": "1234567765431056709",
269+
"type": 1,
270+
"event": {
271+
"type": "LOBBY_MESSAGE_CREATE",
272+
"timestamp": "2024-10-18T18:41:21.109604",
273+
"data": {
274+
"id": "1397729799727878254",
275+
"type": 0,
276+
"content": "welcome to the party!",
277+
"lobby_id": "1397729744753266719",
278+
"channel_id": "1397729744753266719",
279+
"author": {
280+
// user data
281+
},
282+
"flags": 65536,
283+
"application_id": "1234567765431056709"
284+
}
285+
}
286+
}
287+
```
288+
289+
#### Lobby Message Update
290+
291+
`LOBBY_MESSAGE_UPDATE` is sent when a message is updated in a lobby.
292+
293+
###### Lobby Message Update Structure
294+
295+
The inner payload is a [lobby message object](/docs/events/webhook-events#lobby-message-object) with additional fields for message updates.
296+
297+
###### Lobby Message Update Example
298+
299+
```json
300+
{
301+
"version": 1,
302+
"application_id": "1234567765431056709",
303+
"type": 1,
304+
"event": {
305+
"type": "LOBBY_MESSAGE_UPDATE",
306+
"timestamp": "2025-08-05T20:39:19.587872",
307+
"data": {
308+
"id": "1402390388030832792",
309+
"type": 0,
310+
"content": "noice",
311+
"lobby_id": "1402385687281537066",
312+
"channel_id": "1402389638311841883",
313+
"author": {
314+
// user data
315+
},
316+
"edited_timestamp": "2025-08-05T20:39:19.557970+00:00",
317+
"flags": 0,
318+
"timestamp": "2025-08-05T20:38:43.660000+00:00"
319+
}
320+
}
321+
}
322+
```
323+
324+
#### Lobby Message Delete
325+
326+
`LOBBY_MESSAGE_DELETE` is sent when a message is deleted from a lobby.
327+
328+
###### Lobby Message Delete Structure
329+
330+
| Field | Type | Description |
331+
|----------|-----------|-----------------------------------------------|
332+
| id | snowflake | ID of the deleted message |
333+
| lobby_id | snowflake | ID of the lobby where the message was deleted |
334+
335+
###### Lobby Message Delete Example
336+
337+
```json
338+
{
339+
"version": 1,
340+
"application_id": "1234567765431056709",
341+
"type": 1,
342+
"event": {
343+
"type": "LOBBY_MESSAGE_DELETE",
344+
"timestamp": "2025-08-05T21:44:09.412957",
345+
"data": {
346+
"id": "1402406637632884857",
347+
"lobby_id": "1402399883394285659"
348+
}
349+
}
350+
}
351+
```
352+
353+
#### Game Direct Message Create
354+
355+
`GAME_DIRECT_MESSAGE_CREATE` is sent when a direct message is created while at least one user has an active Social SDK session.
356+
357+
###### Game Direct Message Create Structure
358+
359+
The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).
360+
361+
###### Game Direct Message Create Example
362+
363+
```json
364+
{
365+
"version": 1,
366+
"application_id": "1234567765431056709",
367+
"type": 1,
368+
"event": {
369+
"type": "GAME_DIRECT_MESSAGE_CREATE",
370+
"timestamp": "2025-08-14T18:09:38.063234",
371+
"data": {
372+
"id": "1405614357781545021",
373+
"type": 0,
374+
"content": "get in friend, we're going raiding",
375+
"channel_id": "1405604229820715098",
376+
"author": {
377+
// user data
378+
},
379+
"timestamp": "2025-08-14T18:09:37.947000+00:00",
380+
"application_id": "1234567765431056709",
381+
"attachments": []
382+
}
383+
}
384+
}
385+
```
386+
387+
#### Game Direct Message Update
388+
389+
`GAME_DIRECT_MESSAGE_UPDATE` is sent when a direct message is updated while at least one user has an active Social SDK session.
390+
391+
###### Game Direct Message Update Structure
392+
393+
The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).
394+
395+
###### Game Direct Message Update Example
396+
397+
```json
398+
{
399+
"version": 1,
400+
"application_id": "1234567765431056709",
401+
"type": 1,
402+
"event": {
403+
"type": "GAME_DIRECT_MESSAGE_UPDATE",
404+
"timestamp": "2025-08-14T16:44:31.847073",
405+
"data": {
406+
"id": "1405591838810706081",
407+
"content": "almost ready to queue?",
408+
"channel_id": "1404960877324533784",
409+
"author": {
410+
// user data
411+
},
412+
"recipient_id": "1404960877324533784"
413+
}
414+
}
415+
}
416+
```
417+
418+
#### Game Direct Message Delete
419+
420+
`GAME_DIRECT_MESSAGE_DELETE` is sent when a direct message is deleted while at least one user has an active Social SDK session.
421+
422+
###### Game Direct Message Delete Structure
423+
424+
The inner payload is a [message object](/docs/events/webhook-events#message-object) or [passthrough message object](/docs/events/webhook-events#passthrough-message-object).
425+
426+
###### Game Direct Message Delete Example
427+
428+
```json
429+
{
430+
"version": 1,
431+
"application_id": "1234567765431056709",
432+
"type": 1,
433+
"event": {
434+
"type": "GAME_DIRECT_MESSAGE_DELETE",
435+
"timestamp": "2025-08-20T17:01:50.099204",
436+
"data": {
437+
"id": "1407771600643686503",
438+
"type": 0,
439+
"content": "cant make it in time",
440+
"channel_id": "1405604229820715098",
441+
"author": {
442+
// user data
443+
},
444+
"timestamp": "2025-08-20T17:01:44.725000+00:00",
445+
"flags": 0,
446+
"attachments": [],
447+
"components": []
448+
}
449+
}
450+
}
451+
```
452+
453+
## Social SDK Message Objects
454+
455+
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.
456+
457+
- [Lobby messages](/docs/events/webhook-events#lobby-message-object) include lobby-specific fields like `lobby_id`
458+
- [Standard Discord messages](/docs/events/webhook-events#message-object) in SDK contexts may include additional fields
459+
- [Passthrough messages](/docs/events/webhook-events#passthrough-message-object) are used for communication between provisional accounts
460+
461+
These objects are used in the webhook events `LOBBY_MESSAGE_*` and `GAME_DIRECT_MESSAGE_*` depending on the messaging context.
462+
463+
### Lobby Message Object
464+
465+
Represents a message sent in a lobby or [Linked Channel](/docs/discord-social-sdk/development-guides/linked-channels).
466+
467+
###### Lobby Message Structure
468+
469+
| Field | Type | Description |
470+
|-----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
471+
| id | snowflake | ID of the message |
472+
| type | integer | [Type of message](/docs/resources/message#message-object-message-types) |
473+
| content | string | Contents of the message |
474+
| lobby_id | snowflake | ID of the lobby where the message was sent |
475+
| channel_id | snowflake | ID of the channel the message was sent in |
476+
| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message |
477+
| metadata? | object | Additional metadata for the message (key-value pairs) |
478+
| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
479+
| application_id? | snowflake | ID of the application (only present during active Social SDK sessions) |
480+
481+
### Message Object
482+
483+
Standard [Message Object](/docs/resources/message#messages-resource) with additional fields.
484+
485+
###### Additional Fields
486+
487+
| Field | Type | Description |
488+
|-----------|----------------------------------------------------------|-----------------------------------------------------------------------------------------|
489+
| lobby_id? | snowflake | ID of the lobby where the message was created (only present in Linked Channel messages) |
490+
| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information |
491+
492+
### Passthrough Message Object
493+
494+
Represents a message between provisional users that exists only in-game.
495+
496+
###### Passthrough Message Structure
497+
498+
| Field | Type | Description |
499+
|----------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
500+
| id | snowflake | ID of the message |
501+
| type | integer | [Type of message](/docs/resources/message#message-object-message-types) |
502+
| content | string | Contents of the message |
503+
| channel_id | snowflake | ID of the channel the message was sent in |
504+
| recipient_id | snowflake | ID of the message recipient |
505+
| author | [user object](/docs/resources/user#user-object-user-structure) | Author of the message |
506+
| flags | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
507+
| application_id | snowflake | ID of the application that created the message |
508+
| channel | [channel object](/docs/resources/channel#channel-object) | Channel object with recipient information |
509+
510+
:::info
511+
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.
512+
:::

0 commit comments

Comments
 (0)