Matrix (Application Service)

Matrix is an open, decentralized messaging protocol. ClawCentral connects as a Matrix Application Service (AS), not as a regular user account. This means ClawCentral registers with your homeserver as an AS, and the homeserver forwards relevant events to ClawCentral's managed platform via HTTP.

Status: direct messages and rooms are supported. Text, media, reactions, and threads are supported. Polls (send) and location messages are supported.

Webhook URL

https://<your-tenant>.clawcentral.io/webhooks/matrix

ClawCentral receives Matrix AS transactions at PUT /webhooks/matrix/transactions/:txnId.

Required credentials

Set these in Admin UI → Settings → Tenant Settings → Secrets:

Secret	Description
MATRIX_HS_TOKEN	Homeserver token — used by the homeserver to authenticate requests it sends to ClawCentral
MATRIX_AS_TOKEN	Application Service token — used by ClawCentral to authenticate requests it sends to the homeserver
MATRIX_HOMESERVER_URL	Base URL of your Matrix homeserver (e.g., https://matrix.example.org)
MATRIX_BOT_USER_ID	Full Matrix ID of the bot user (e.g., @clawcentral:example.org)

ClawCentral verifies the MATRIX_HS_TOKEN on every inbound AS transaction automatically.

How Matrix Application Services work

An Application Service is a trusted server-side integration that registers with a homeserver. Unlike a regular bot user that logs in with a password, an AS:

1. Has a dedicated hs_token (homeserver authenticates to the AS) and as_token (AS authenticates to the homeserver)
2. Declares a namespace of user IDs and/or room aliases it controls
3. Receives a copy of all matching events from the homeserver via PUT /_matrix/app/v1/transactions/:txnId

ClawCentral acts as the AS endpoint. You provide the AS registration parameters to your homeserver administrator, who adds them to the homeserver configuration.

Setup

Step 1: Generate tokens

Generate two random secrets — one for hs_token and one for as_token. These can be any long random string (e.g., 32+ hex characters).

Step 2: Provide AS registration parameters to your homeserver admin

You do not place a registration file on ClawCentral's infrastructure. Instead, provide the following parameters to your homeserver administrator so they can register the AS with the homeserver:

# AS registration parameters — provide these to your homeserver admin
id: clawcentral
url: https://<your-tenant>.clawcentral.io/webhooks/matrix
as_token: <your-as-token>
hs_token: <your-hs-token>
sender_localpart: clawcentral
namespaces:
  users:
    - exclusive: false
      regex: "@clawcentral:.*"
  rooms: []
  aliases: []
rate_limited: false
protocols: []

The homeserver admin adds this to the homeserver's app_service_config_files list (for Synapse: app_service_config_files: ["path/to/clawcentral.yaml"]) and restarts the homeserver.

Step 3: Enter credentials in Admin UI

1. Open your Admin UI at https://<your-tenant>.clawcentral.io/
2. Go to Settings → Tenant Settings → Secrets
3. Enter all four secrets:
   • MATRIX_HS_TOKEN — the hs_token you generated
   • MATRIX_AS_TOKEN — the as_token you generated
   • MATRIX_HOMESERVER_URL — your homeserver base URL
   • MATRIX_BOT_USER_ID — the bot's full Matrix ID (e.g., @clawcentral:example.org)
4. Save

Step 4: Start a conversation

Once the homeserver admin has registered the AS and restarted the homeserver:

1. Open any Matrix client (Element, Cinny, etc.)
2. Start a DM with the bot user ID you configured
3. Send a message

Routing model

• Replies always go back to Matrix.
• DMs map to the user's main session.
• Rooms map to group sessions keyed by room ID.

Access control (DMs)

• Default: unknown senders receive a pairing code; messages are ignored until approved.
• Approve senders via the Admin UI.
• Use full Matrix user IDs for allowlists (e.g., @user:server). Display names and bare localparts are ambiguous and are not used for allowlist matching.

Rooms (groups)

• Default: group messages require @-mention.
• Rooms can be allowlisted by room ID or alias via the Admin UI.
• Room IDs take the form !roomId:example.org.
• Invites are auto-joined by default; this can be restricted in Admin UI settings.

Threads

• Reply threading is supported.
• Replies stay in threads by default (inbound thread replies are preserved).

Capabilities

Feature	Status
Direct messages	Supported
Rooms	Supported
Threads	Supported
Media	Supported
Reactions	Supported (send/read)
Polls	Send supported; inbound poll starts are converted to text (responses/ends ignored)
Location	Supported (geo URI; altitude ignored)

Troubleshooting

Common failures:

• Room messages ignored: Room is blocked by group policy or not in the room allowlist. Add the room ID via Admin UI → Settings → Channels → Matrix.
• DMs ignored: Sender is pending approval. Approve via the Admin UI pairing section.
• Homeserver not forwarding events: Confirm the AS was registered correctly and the homeserver was restarted. Verify the url field in the AS registration points to https://<your-tenant>.clawcentral.io/webhooks/matrix.
• Authentication errors: Check that MATRIX_HS_TOKEN in Tenant Settings → Secrets matches hs_token in the AS registration file the homeserver admin used.

For further triage: Channel troubleshooting.

Related

• Channel troubleshooting
• Security