Double Puppeting

When you bridge your Matrix server to an external service like Whatsapp or Telegram you are basically logging in into the external service with your own credentials and create a corresponding Matrix room in which the bridge will take care to synchronize all the messages sent by people in the external service and vice-versa, publish to the external service whatever users in the Matrix room will publish.

In order to do so, the bridge will act like your external user because it is actually you on the external service. What the bridge will actually do is create a fake alias in the Matrix room with your external service username and post using this alias in Matrix.

This leads to some limitations. Let's assume you have bridged a private chat between you and Paolo (an immaginary friend in your external service). You have now in the room(=chat on the external service) three actors:

• Yourself as the Matrix user
• Paolo, actually a copy of Paolo linked to the external Paolo
• Yourself-copy, which is linked to the external yourself

Yourself and yourself-copy have the same name, but actually are two different users in the chat. This means that yourself cannot sent “admin” commands to the external chat, for example issue bot commands or perform admin actions, because yourself is not the administrator of the external chat: yourself-copy is. Also, every private conversation has three users instead of two.

Double-Puppeting comes to the rescue! It let's you login the bridge as yourself in Matrix, so that there is no need for yourself-copy in any room, and it will be yourself to post directly to the external chat, so that yyourself will be able to issue any admin command and so on.

Note: everything above applies only to the Matrix rooms, nothing changes for the external chat, amnd nobody there will notice anything!

This page of the Mautrix Bridges explains it pretty good. To enable double puppeting you need to create a new Appservices, register it to your Matrix server and set the secret into each bridge that you want to double-puppet.

Create the double-puppeting-registration.yaml:

# The ID doesn't really matter, put whatever you want.
id: doublepuppet
# The URL is intentionally left empty (null), as the homeserver shouldn't
# push events anywhere for this extra appservice. If you use a
# non-spec-compliant server, you may need to put some fake URL here.
url:
# Generate random strings for these three fields. Only the as_token really
# matters, hs_token is never used because there's no url, and the default
# user (sender_localpart) is never used either.
as_token: << generate a random string here >>
hs_token: << generate a random string here >>
sender_localpart: whatever-not-used-but-cannot-be-empty
# Bridges don't like ratelimiting. This should only apply when using the
# as_token, normal user tokens will still be ratelimited.
rate_limited: false
namespaces:
  users:
  # Replace your\.domain with your server name (escape dots for regex)
  - regex: '@.*:chat\.mydomain\.com'
    # This must be false so the appservice doesn't take over all users completely.
    exclusive: false

Check the comments in the example above. You need to generate your tokens!

Now, register it. If using Conduwuit, follow the usual app-service registration described here.

Open the bridge config.yaml file and locate the section similar to:

double_puppet:
    # Servers to always allow double puppeting from.
    # This is only for other servers and should NOT contain the server the bridge is on.
    servers:
        anotherserver.example.org: https://matrix.anotherserver.example.org
    # Whether to allow client API URL discovery for other servers. When using this option,
    # users on other servers can use double puppeting even if their server URLs aren't
    # explicitly added to the servers map above.
    allow_discovery: false
    # Shared secrets for automatic double puppeting.
    secrets:
        chat.mydomain.com: as_token:<< copy your as_token string here >>

Now, if you are enabling bridges and double-puppeting for your server, leave allow_discovery: false and do not specify anything under servers:.