application-service.md

Application Service

WARNING: These features are currently highly experimental. They can be removed or modified without notice.
All the features requires a Homeserver capable of connecting Application Services.

The following capabilities are provided in this feature:

• Admin commands
• Email Notification about room invites by Matrix IDs
• Auto-reject of expired 3PID invites

Setup

NOTE: Make sure you are familiar with configuration format and rules.

Integration as an Application service is a three steps process:

1. Create the baseline ma1sd configuration to allow integration.
2. Integrate with the homeserver.
3. Configure the specific capabilities, if applicable.

Configuration

Variables

Under the appsvc namespace:

Key	Type	Required	Default	Purpose
enabled	boolean	No	false	Globally enable/disable the feature
user.main	string	No	ma1sd	Localpart for the main appservice user
endpoint.toHS.url	string	Yes	None	Base URL to the Homeserver
endpoint.toHS.token	string	Yes	None	Token to use when sending requests to the Homeserver
endpoint.toAS.url	string	Yes	None	Base URL to ma1sd from the Homeserver
endpoint.toAS.token	string	Yes	None	Token for the Homeserver to use when sending requests to ma1sd

Example

appsvc:
  enabled: true
  endpoint:
    toHS:
      url: 'http://localhost:8008'
      token: 'ExampleTokenToHS-ChangeMe!'
    toAS:
      url: 'http://localhost:8090'
      token: 'ExampleTokenToAS-ChangeMe!'

Integration

Synapse

Under the appsvc.registration.synapse namespace:

Key	Type	Required	Default	Purpose
id	string	No	appservice-ma1sd	The unique, user-defined ID of this application service. See spec.
file	string	Yes	None	If defined, the synapse registration file that should be created/updated

Example

appsvc:
  registration:
    synapse:
      file: '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'

Edit your homeserver.yaml and add a new entry to the appservice config file, which should look something like this:

app_service_config_files:
  - '/etc/matrix-synapse/ma1sd-appservice-registration.yaml'
  - ...

Restart synapse when done to register ma1sd.

Others

See your Homeserver documentation on how to integrate.

Capabilities

Admin commands

Setup

Min config:

appsvc:
  feature:
    admin:
      allowedRoles:
        - '+aMatrixCommunity:example.org'
        - 'SomeLdapGroup'
        - 'AnyOtherArbitraryRoleFromIdentityStores'

Use

The following steps assume:

• matrix.domain set to example.org
• appsvc.user.main set to ma1sd or not set

1. Invite @ma1sd:example.org to a new direct chat
2. Type !help to get all available commands

Email Notification about room invites by Matrix IDs

This feature allows for users found in Identity stores to be instantly notified about Room Invites, regardless if their account was already provisioned on the Homeserver.

Requirements

• Identity store(s) supporting the Profile feature
• At least one email entry in the identity store for each user that could be invited.

Configuration

In your ma1sd config file:

synapseSql:
  enabled: false ## Do not use this line if Synapse is used as an Identity Store
  type: '<DB TYPE>'
  connection: '<DB CONNECTION URL>'

The synapseSql section is optional. It is used to retrieve display names which are not directly accessible in this mode. For details about type and connection, see the relevant documentation. If you do not configure it, some placeholders will not be available in the notification, like the Room name.

You can also change the default template of the notification using the generic.matrixId template option.
See the Template generator documentation for more info.

Test

Invite a user which is part of your domain while an appropriate Identity store is used.

Auto-reject of expired 3PID invites

TBC