INTEGRATIONS · MATRIX

Connect Matrix and Element

Element is a Matrix client. Use PersonaStack’s Matrix integration to give a persona access to rooms and direct messages on your Matrix server.

Have the account ready

You need the Matrix server address, the account’s username and password, and its Security Phrase. The Security Phrase is the phrase for Matrix secure backup. It is different from the account password.

If you do not have a Security Phrase, check the security or secure-backup settings in your Matrix client before starting. Make sure the account can access the rooms you want the persona to use.

1. Start the connection

1. Open Integrations → Matrix.
2. Choose Connect Matrix.
3. Enter an Integration Name that identifies the account or purpose.
4. Choose sending and reading access.
5. Enter the Matrix server, then continue to sign in.

Use Connect directly for a server PersonaStack can reach directly. The cluster route is for a server that must be reached through a connected Kubernetes cluster. You can leave that advanced option alone for a normal public server.

2. Choose conversations

When reading is enabled, choose the rooms and direct messages the persona should watch. Use the conversation picker to select a small starting set. Select the explicit all-access option only when that matches your intended scope.

A selected-conversation setup with no selected rooms does not mean “watch everything.” After setup, check the saved panel’s conversation summary to confirm the choice.

3. Authorize the device

At Authorize device, enter the Matrix account’s Security Phrase and choose Authorize device. This step is required even for send-only access.

Keep the phrase in this setup field. Do not send it to a persona in chat. If authorization fails, read the displayed message and correct the phrase before trying again. A password, recovery-key file, or emoji confirmation is not a substitute for this field.

4. Review and assign

Review the identity, access, rooms, encryption, and route summary. Choose Create integration when setup is ready. Wait for the saved connection’s startup status to settle before trying a conversation.

Open the persona’s settings and select the Matrix connection under Integrations. Enable Wake on incoming events if incoming messages should start that persona. Send a short message from another Matrix account in one of the selected rooms.

Check a connection that stopped receiving messages

Open Integrations → Matrix and read the saved connection’s status. Confirm that reading is enabled, the intended rooms are selected, and the persona still has this connection with Wake on incoming events enabled.

PersonaStack renews expiring credentials when the Matrix server provides a refresh token. This keeps the same PersonaStack device. A temporary server or network failure shows a connection warning while the existing connection retries. A connected status requires a working receive path.

If the status says the connection must be recreated, use Create new connection. Turning off reading does not repair rejected credentials. Authorize the new device, select its rooms, and update the persona’s selected Matrix connection.

If the status itself is unavailable, wait for it to reconnect before treating the previous status as current. Sending and receiving can fail independently. Include the connection’s name and displayed error when reporting a problem. Do not include passwords, tokens, or the Security Phrase.

Manage rooms later

The saved connection has separate controls for Save access, Select conversations, Save rooms, and Save route. Use Review invites when the account has room invitations to inspect.

Open Matrix connections ↗

Need a hand? Contact the PersonaStack team.