Matrix

Sophon connects to any Matrix homeserver using an access token. This works with any Matrix client, including Element, FluffyChat, and Nheko.

Prerequisites

A Matrix homeserver (self-hosted or a public server like matrix.org)
A dedicated bot account on the homeserver

Step-by-Step Setup

1. Create a Bot Account

Create a dedicated account for Sophon on your homeserver. You can do this through:

Element Web: Register a new account at your homeserver's registration page
CLI (synapse admin API): Use the admin API if you run your own server

Use a descriptive username like @sophon:your-server.com.

2. Get an Access Token

Option A: From Element

Log into Element with the bot account
Go to Settings > Help & About
Scroll to Advanced
Click to reveal the Access Token
Copy the token

Option B: Via API

curl -X POST "https://your-server.com/_matrix/client/r0/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "sophon",
    "password": "your-password"
  }'

Copy the access_token from the response.

Important: After extracting the token, do not log out of the session — this would invalidate the token. The bot account should remain logged in.

3. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select Matrix
Enter the Homeserver URL (e.g., https://matrix.org)
Enter the Access Token
Enter the Bot User ID (e.g., @sophon:matrix.org)
Click Test Connection
Click Activate

4. Invite the Bot

Invite the bot user to any rooms where you want Sophon to listen:

In your Matrix client, open the room
Invite @sophon:your-server.com
Sophon will auto-join and start responding

Configuration Reference

Field	Type	Required	Description
`homeserverUrl`	url	Yes	Matrix homeserver base URL (e.g., `https://matrix.org`)
`accessToken`	secret	Yes	Access token for the bot account
`userId`	text	Yes	Full Matrix user ID (e.g., `@sophon:matrix.org`)

channels.json Example

{
  "id": "matrix-bot",
  "type": "matrix",
  "name": "Sophon Matrix Bot",
  "enabled": true,
  "config": {
    "homeserverUrl": "https://matrix.org",
    "accessToken": "<encrypted>",
    "userId": "@sophon:matrix.org"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Troubleshooting

"M_UNKNOWN_TOKEN" — The access token is invalid or expired. This often happens if you logged out of the session that generated the token. Generate a new token via the login API.
Bot doesn't respond in rooms — The bot must be invited to the room. Check that the bot has joined (not just been invited). Also verify groupBehavior settings.
"M_FORBIDDEN" — The bot doesn't have permission to send messages in the room. Check the room's power levels.
Homeserver unreachable — Verify the homeserver URL is correct and includes the protocol (https://). For self-hosted servers, ensure the homeserver is accessible from the machine running Sophon.

On this page