diff --git a/proposals/4214-widgets-as-messages.md b/proposals/4214-widgets-as-messages.md new file mode 100644 index 00000000000..8e6ac96f94f --- /dev/null +++ b/proposals/4214-widgets-as-messages.md @@ -0,0 +1,213 @@ +# MSC4214: Embedding Widgets in Messages + +*This proposal introduces the ability to embed widgets directly within messages in the Matrix +timeline. By allowing users to post interactive elements like games, polls, or other tools directly +in messages, this MSC enhances user engagement and interactivity beyond the current room-scoped +widgets.* + +## Proposal + +Currently, Matrix supports room-level widgets that provide collaborative and interactive +capabilities but are not tied to individual messages. This MSC proposes a method to embed widgets +directly within messages, enabling rich, contextual interactions without attaching them as +room-level widgets. + +This proposal uses the extensible events format (per MSC1767) to ensure future compatibility and +flexibility, aligning with modern Matrix practices. The aim is to keep the implementation +lightweight while enabling various use cases. + +## Event Schema + +### New Event Type + +- **Event Type**: `m.widget` +- **Format**: Extensible event + +### Event Content + +The message event containing the embedded widget will include the following fields: + +- **`m.text`**: A caption for the widget, providing context or instructions (similar to image + captions). Clients that do not support widgets should display this field as a fallback. +- **`m.widget`**: An object containing details about the widget: + - `url`: The URL of the widget (e.g., a hosted game or tool). + - `name`: A human-readable name for the widget. + - `type` *(optional)*: A namespaced identifier to distinguish different types of widgets. + - `data` *(optional)*: An object containing any initial configuration or data required by the widget. + - `id` *(optional)*: A unique identifier for the widget instance. + +### Example Event + +```json +{ + "type": "m.widget", + "content": { + "m.text": [ + {"body": "Check out this interactive Tic-Tac-Toe game!"} + ], + "m.widget": { + "url": "", + "name": "Tic-Tac-Toe", + "type": "net.example.tictactoe", + "data": { + "game_id": "abc123" + }, + "id": "widget-xyz789" + } + } +} +``` + +## Client-Server API Changes + +### **Posting a Widget in a Message** + +To post a widget, clients send a `m.widget` message event containing the structure above. Clients +that do not support widgets will render the `m.text` caption as a fallback. + +### **Rendering and Interaction** + +- **Widget Rendering**: Clients supporting `m.widget` should render the widget inline within the + timeline. Widgets must be sandboxed using an `