Matrix API Widgets

Matrix API Widgets integrates Drupal with the Matrix Widget API, enabling Drupal pages to run as authenticated embedded applications inside Matrix clients such as Element. When a Drupal page is pinned as a widget in a Matrix room, this module handles the identity handshake so the Matrix user is automatically recognized as their linked Drupal account — no separate Drupal login required.

Note: "Matrix widgets" and "Drupal widgets" are unrelated concepts. This module has nothing to do with Drupal's block or layout widgets. It implements the Matrix specification for embedding web applications inside Matrix room clients.

Features

• Widget registration — register any Drupal URL as a widget in a Matrix room by writing the widget state event (im.vector.modular.widgets / m.widget) via the Matrix API client service. Widgets can be scoped to specific rooms and made visible to all room members.
• OIDC authentication bridge — Matrix clients supporting the Widget API can authenticate a widget's user via the homeserver's OIDC provider. This module validates the token supplied by the Matrix client and establishes a Drupal session for the corresponding account, using Matrix API Identity to resolve the Matrix ID to a Drupal user. The widget opens already authenticated — no login form is presented to the user.
• Transport-agnostic message passing — exposes the Widget API postMessage channel to Drupal's event system, so custom modules and ECA
  models can send and receive messages between the Matrix client and the embedded Drupal page.

This module provides the infrastructure for building Matrix-embedded Drupal applications. It does not ship pre-built widget content or pages; those are provided by your site's custom modules or configuration.

Post-Installation

After enabling the module, configuration depends on your use case:

• To register a Drupal URL as a widget in a Matrix room, use the provided service or an ECA action to write the widget state event to the room via the Matrix API client. The room, widget ID, widget URL, and display name are all configurable.
• To enable the OIDC authentication bridge, configure the homeserver's OIDC issuer URL at Admin → Config → Web Services → Matrix API → Widget Settings. Drupal will validate tokens from that issuer and map authenticated Matrix users to their linked Drupal accounts via Matrix API Identity.
• The postMessage event bridge fires Drupal events you can subscribe to in custom code or wire up in ECA without any additional configuration.

This module is under active development. Not all features described above may be available in the current release — check the issue queue for status.

Additional Requirements

• Matrix API (>=3.0) — required. Provides the Matrix client service and plugin infrastructure.
• A Matrix homeserver (self-hosted Synapse or compatible) configured with OIDC support for the authentication bridge.
• A Matrix client that supports the Widget API (Element, Element Web, or compatible).

Recommended modules/libraries

• Matrix API Identity — strongly recommended. Links Drupal user accounts to Matrix IDs so the OIDC bridge can resolve authenticated Matrix users to the correct Drupal account.
• ECA (Event-Condition-Action) — use ECA to react to widget message events and trigger widget registration without custom code.

Similar projects

There are no other Drupal modules implementing the Matrix Widget API at this time. For general Matrix integration without the widget embedding use case, see the href="https://www.drupal.org/project/matrix_api">Matrix API base module and its companion modules.

Supporting this Module

Development is sponsored by Freelock. If this module is useful to you, consider href="https://www.drupal.org/project/matrix_api">starring the project on Drupal.org or contributing patches and issue reports.

Community Documentation

Developer documentation is included with the Matrix API module:

• docs/integration-overview.md — architecture and two-way sync design
• docs/plugin-api.md — plugin developer reference