@matrix-widget-toolkit/api

This is package that wraps matrix-widget-api to provide a more convenient API. For now, the API includes:

• A WidgetApi interface with more advanced features.
• Helper functions for registering the Widget in rooms.
• Types and helper functions for common events, like power levels, room members, redactions, and relations.

Usage

Install it with:

yarn add @matrix-widget-toolkit/api

Creating a WidgetApi instance

Creating the WidgetApi instance should be done as early as possible in your code because otherwise the widget misses the connection establishment by the widget host (especially on Safari).

import { WidgetApiImpl } from '@matrix-widget-toolkit/api';

const widgetApi = await WidgetApiImpl.create();

Request capabilities

You can request additional capabilities at any time using requestCapabilities(). A call returns a promise that resolves once the user approved the capabilities.

import { WidgetEventCapability } from 'matrix-widget-api';

await widgetApi.requestCapabilities([
  WidgetEventCapability.forStateEvent(
    EventDirection.Send,
    STATE_EVENT_POWER_LEVELS,
  ),
]);

Receiving state events

You can read state events once from the current room using receiveStateEvents():

const events = await widgetApi.receiveStateEvents(STATE_EVENT_ROOM_NAME);

// events is an array of state events

Warning Don't assume the type of the returned events, always validate that they have the expected schema.

Observing state event changes

You can listen to state event changes using observeStateEvents(). Note that the initial state is also returned.

const subscription = widgetApi
  .observeStateEvents(STATE_EVENT_POWER_LEVELS)
  .subscribe(async (event) => {
    // The callback is always called if a state event changes
  });

// Don't forget to unsubscribe later
subscription.unsubscribe();

Sending state events

You can send state events using sendStateEvent(). It returns a promise that resolves once the event has been sent.

await widgetApi.sendStateEvent('m.room.topic', {
  topic: 'A brief description',
});

Warning Avoid sending event content that has no changes, as the returned promise doesn't resolve in this case.

Receiving room events

You can read the current room events using receiveRoomEvents(). Note that this API only returns the events that are currently in the view of the client. There is no guarantees to read all events from the room. Therefore this function is of limited use. For more details and solutions, see MSC3869.

const events = await widgetApi.receiveRoomEvents('com.example.test');

// events is an array of room events

Observing room events

You can listen to room events using observeRoomEvents().

const subscription = widgetApi
  .observeRoomEvents(ROOM_EVENT_REACTION)
  .subscribe(async (event) => {
    // Callback is called every time a room event is received
  });

// Don't forget to unsubscribe later
subscription.unsubscribe();

Sending room events

You can send room events using sendRoomEvent(). It returns a promise that resolves once the event has been sent.

await widgetApi.sendRoomEvent('m.room.redaction', {
  redacts: '$event-id',
});

Read related events

You can use readEventRelations() to read events releated to an event via m.relates_to. It provides an API with cursors that you can use to page through the results.

const result = await widgetApi.readEventRelations(eventId, {
  limit: 50,
  from,
  relationType: 'm.annotation',
  eventType: 'm.reaction',
});

// result contains the events and cursor for paging further though the events

Opening Modal Widgets

You can open modal widgets using openModal(). It returns a promise that resolves with the result of the modal.

Inside the modal widget, you can use observeModalButtons() to listen to clicks on the bottom buttons of the modal. You can use setModalButtonEnabled() to disable buttons from within the widget. Once you are done, you can call closeModal() to close the modal and pass the results back to the main widget.