Matrix
Connect Matrix when you want an agent available in Matrix direct messages or rooms.
Prerequisites
- An existing Cloud Agents agent.
- A Matrix bot account.
- A Matrix access token for that bot account.
- An unencrypted direct message or room.
End-to-end encrypted Matrix rooms are not supported in the current Matrix channel.
Connect it to Cloud Agents
- Open Settings -> Channels.
- Create a new channel and choose Matrix.
- Select the agent that should receive messages.
- Enter the homeserver URL, for example
https://matrix.example.org. - Enter the Matrix bot access token.
- Optionally restrict allowed room IDs, allowed user IDs, and free-response room IDs.
- Create the channel, then invite the bot into a DM or room.
- Run the channel test.
The bot auto-joins allowed invites by default. In DMs, it replies to every message. In rooms, it replies only when mentioned unless the room is listed in freeResponseRoomIds.
Recommended settings
| Setting | Recommendation |
|---|---|
| Allowed rooms | Restrict to known rooms when the bot account joins multiple rooms. |
| Allowed users | Use when the bot should answer only approved users. |
| Free-response rooms | Add room IDs where the agent may reply without being mentioned. |
| Auto-join | Keep on if the bot should accept allowed room invites. |
| Thread isolation | Keep on for threaded or reply-based conversations. |
Verify
Open the channel detail page and run Test. A healthy channel confirms the bot account and active status.
Troubleshooting
- Bot does not respond in a room: mention the bot or add the room ID to free-response rooms.
- Bot does not join an invited room: check auto-join and allowed room IDs.
- Messages are ignored: confirm the homeserver URL, access token, allowed room IDs, and allowed user IDs.
- Encrypted rooms are ignored: use an unencrypted room for this channel.