{"library":"matrix-widget-api","title":"Matrix Widget API SDK","description":"The `matrix-widget-api` package provides a JavaScript/TypeScript SDK for both Matrix widgets and the clients that host them, facilitating secure and standardized communication. It allows widgets to request capabilities (like sending messages or accessing state) and clients to drive widget behavior and respond to these requests. Currently at stable version 1.17.0, the library typically sees minor releases on a monthly or bi-monthly cadence, introducing new features, bug fixes, and sometimes breaking changes due to the evolving nature of the Matrix widget specification (which is not yet fully standardized). Its key differentiator is being the official SDK from Matrix.org, ensuring alignment with their reference implementations, though this also means it may be subject to changes as the underlying specification matures.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install matrix-widget-api"],"cli":null},"imports":["import { WidgetApi } from 'matrix-widget-api';","import { ClientWidgetApi } from 'matrix-widget-api';","import { MatrixCapabilities } from 'matrix-widget-api';","import { WidgetApiToWidgetAction } from 'matrix-widget-api';"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import { WidgetApi, MatrixCapabilities, WidgetApiToWidgetAction } from 'matrix-widget-api';\n\n// In a widget:\nconst widgetId = null; // Supply widget ID if known, otherwise null\nconst api = new WidgetApi(widgetId);\n\n// Request necessary capabilities early\napi.requestCapability(MatrixCapabilities.Screenshots);\napi.requestCapabilities([MatrixCapabilities.Stickerpicker, MatrixCapabilities.SendEvent]);\n\n// Add custom action handlers if your widget needs to respond to specific events\napi.on(`action:${WidgetApiToWidgetAction.UpdateVisibility}`, (ev) => {\n    ev.preventDefault(); // Indicate that this widget is handling the event\n    console.log(\"Visibility updated:\", ev.detail); // Custom handling logic here\n    api.transport.reply(ev.detail, {}); // Acknowledge receipt\n});\n\napi.on(\"action:com.example.my_custom_action\", (ev) => {\n    ev.preventDefault();\n    console.log(\"Received custom action:\", ev.detail);\n    api.transport.reply(ev.detail, { status: \"received\", processed: true });\n});\n\n// Start the communication messaging\napi.start();\n\n// If your widget doesn't need to wait for an iframe load event, inform the client it's ready\n// (Important for widgets that initialize quickly)\napi.sendContentLoaded();\n\n// Later, send messages or update widget state\napi.setAlwaysOnScreen(true); // Example: request the client to keep the widget always visible\napi.transport.send(\"com.example.another_action\", { data: \"hello from widget\" });\n\nconsole.log(\"Widget API initialized and started.\");\n","lang":"typescript","description":"This quickstart demonstrates how to initialize `WidgetApi` within a Matrix widget, request capabilities, register custom action handlers, start the communication, and send basic messages.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}