Social SDK: Chat History Design Guide

docs/discord-social-sdk/design-guidelines.mdx

@@ -8,6 +8,7 @@ subpages:
   - design-guidelines/branding-guidelines.mdx
   - design-guidelines/unified-friends-list.mdx
   - design-guidelines/direct-messages.mdx
+  - design-guidelines/chat-history.mdx
   - design-guidelines/social-settings.mdx
   - design-guidelines/provisional-accounts.mdx
   - design-guidelines/status-rich-presence.mdx
@@ -43,6 +44,9 @@ If you are looking for a place to get started, we recommend you start with [Prin
   <Card title="Direct Messages" link="/docs/discord-social-sdk/design-guidelines/direct-messages" icon="ChatIcon">
     Best practices for enabling direct messaging between players, facilitating private communication, and enhancing social interactions.
   </Card>
+  <Card title="Chat History" link="/docs/discord-social-sdk/design-guidelines/chat-history" icon="ChatIcon">
+    Best practices for implementing chat history in Discord Social SDK integrations
+  </Card>
   <Card title="Social Settings" link="/docs/discord-social-sdk/design-guidelines/social-settings" icon="ChatIcon">
     Best practices for implementing and managing access to the Discord social settings in games using the Discord Social SDK
   </Card>

docs/discord-social-sdk/design-guidelines/chat-history.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_label: Chat History
+---
+
+[Home](/docs/intro) > [Discord Social SDK](/docs/discord-social-sdk/overview) > [Design Guidelines](/docs/discord-social-sdk/design-guidelines) > Chat History
+
+# Chat History
+
+
+## Style recommendations
+
+Chat history is a highly requested **optional** feature that helps players pick up conversations where they left off—whether they're returning to a lobby or jumping back into a linked channel.
+
+We recommend showing **timestamps** to give players better context about when messages were sent and seen.
+
+![Badge when online elsewhere](images/social-sdk/design-guidelines/ChatHistory-02.webp)
+
+## Display logic
+
+If one player is messaging from a game lobby or linked channel, then chat history is preserved, even if the other player is messaging from Discord.
+
+When players return to a lobby or open a linked channel, we recommend surfacing **10 to 15** of the most recent messages to provide meaningful context. This isn't a hard limit—older messages can be revealed through scroll or loading more content, depending on your UI constraints.
+
+![Message styling](images/social-sdk/design-guidelines/ChatHistory-03.webp)
+
+---
+
+## Resources
+
+- [Development Guide: Creating and Managing Lobbies](/docs/discord-social-sdk/development-guides/managing-lobbies)
+
+## Change Log
+
+| Date          | Changes         |
+|---------------|-----------------|
+| July 02, 2025 | initial release |