Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    0.8.27 • Public • Published

    matrix-appservice-wechaty [M] Matrix

    Wechat (微信) Matrix Application Services Bridge

    Matrix + Wechaty

    Image credit: Gnosis

    Powered by Wechaty NPM Version NPM Docker TypeScript

    What is [Matrix]

    Matrix is an open network for secure, decentralized communication, like Pidgin on your Phone.

    Pidgin try to IM all your friends in one place in Linux, and with Matrix you can have your Phone clinet with your private server which is highly customized. Matrix did not use XMPP protocol, it's server uses REST so that it could be more easy to extend.

    The [Matrix] client Riot is a universal secure chat app entirely under your control. It supports all types of the platforms, including Web/Browser, Android, and iPhone.

    What is matrix-appservice-wechaty

    matrix-appservice-wechaty is a WeChat (微信) Matrix AppService for bridging the Matrix user with WeChat user.

    It has been officially listed at [Matrix] Bridge Page for Wechaty.

    According to Types of Bridging, Wechaty Bot in Matrix will create an Simple Puppeted Bridge with Portal Rooms because we want to bring all conversations from Wechat to Matrix, and let the Matrix user control his account on Wechat.


    1. Support connect to Wechat via Web/iPad/Hostie/Windows/Mac Protocol, with the power of Wechaty
    2. Map all Wechat users/room/official accounts to Matrix virtual users


    1. A Matrix homeserver that supports application services (e.g. Synapse)
    2. Node.js wit NPM, or Docker


    NPM Version npm (next)

    sudo npm install -g matrix-appservice-wechaty

    matrix-appservcie-wechaty is all you need.

    1 Configure config.yaml

    Copy config/config.sample.yaml to config.yaml and update it to match your setup.

    1. domain needs to change to your domain name, which should points to your homeserver.
    2. homeserverUrl needs to change to your homeserver url, with the port number included.
    3. registration needs to change to your registration yaml file name (see next part for how to generate it)

    2 Generate wechaty-registration.yaml

    After we setup the config.yaml, then we can generate the wechaty-registration.yaml file for registing to the home server:

    export APP_SERVICE_ENDPOINT='http://localhost:8788'
    matrix-appservice-wechaty \
      --config  config.yaml \
      --url     "$APP_SERVICE_ENDPOINT" \

    Note: The URL APP_SERVICE_ENDPIOINT is used by the home server to communite with appservice, in this example is: http://localhost:8788. If you have other appservices, or other requirements, pick an appropriate hostname and port.

    3 Register the App Service

    Edit your homeserver.yaml file and update the app_service_config_files entry with the path to the wechaty-registration.yaml file.

    app_service_config_files: ["/data/wechaty-registration.yaml"]

    4 Restart Home Server (Synapse)

    You will then need to restart the synapse server.

    For docker users:

    export SYNAPSE_CONTAINER_ID=$(docker ps | grep synapse | awk '{print $1}')
    docker restart $SYNAPSE_CONTAINER_ID

    Or if you are not using docker:

    synctl restart

    Remember to restart it every time the registration file is updated.

    Launch the Wechaty AppService Bridge

    Let's start the matrix-appservice-wechaty bridge, with the port specified in wechaty-registration.yaml (8788 in the above example)

    export WECHATY_PUPPET=wechaty-puppet-padplus
    export WECHATY_PUPPET_PADPLUS_TOKEN=xxxxxxxxxxxxxxxxxxxxx
    matrix-appservice-wechaty \
      --config  config.yaml \
      --file    wechaty-registration.yaml

    Note: Wechaty is a very powerful framework that supporting Web, iPad, Win32, Mac, iOS protocols of WeChat. Learn more about WeChaty protocols at our Wechaty Puppet Directory, and you can apply for a token for using wechaty-puppet-padplus at our Support Developers Program

    The bridge should start working shortly afterwards.

    The current path ($(pwd)) should have the wechaty-registration.yaml file and config.yaml file. Additional bridge-related data will be stored here.


    Example wechaty-registration.yaml

    id: wechaty
    hs_token: 4f2763d5cc6e931967ec89efdde1123772945184b4cbe99e8fa9538122015e92
    as_token: c27815bdd699d2eaefb499c83f99ce1a7983a9688811269fbcc17b632b0b250e
        - exclusive: true
          regex: '@wechaty_.*'
        - exclusive: true
          regex: '#wechaty_.*'
      rooms: []
    url: matrix.chatie.io:8788
    sender_localpart: wechaty
    rate_limited: false
      - wechaty

    Example config.yaml

    domain: chatie.io
    homeserverUrl: https://matrix.chatie.io
    registration: wechaty-registration.yaml

    Example Docker Compose File


    We have published a docker image wechaty/matrix-appservice for your convenience.

    You can use docker to run matrix-appservice-wechaty bridge by adding the following configs to your docker-compose.yml

      container_name: matrix-appservice-wechaty
      image: wechaty/matrix-appservice
      - ./bridges/matrix-appservice-wechaty:/data
      - default
      - WECHATY_PUPPET_PADPLUS_TOKEN=puppet_padplus_<token>
      - WECHATY_PUPPET=wechaty-puppet-padplus
      command: ["--config", "/data/config.yaml", "--file", "/data/wechaty-registration.yaml", "--port", "8788"]

    Beidge Usage

    1. Talk to Wechaty Bot (@wechaty:your.domain.ltd)
    2. Send the message !login (three times ... wip... )
    3. The wechaty app service bot will then send you a QR Code for scanning by WeChat.

    After scan the QR Code and confirm on your phone, everything will be setup automatically by the wechaty bot.


    Logging in

    1. Start a chat with the bridge bot. The bot should say "This room has been registered as your bridge management/status room." if you started the chat correctly.
    2. Run !login
    3. Log in by scanning the QR code. If the code expires before you scan it, the bridge will send an error to notify you.
      1. Open Wechat on your phone.
      2. Tap Menu or Settings and select Scan.
      3. Point your phone at the image sent by the bot to capture the code.
    4. Finally, the bot should inform you of a successful login and the bridge should start creating portal rooms for all your Wechat groups and private chats.

    Logging out

    Simply run the !logout management command.

    Install Matrix Server

    By following the guide from @spantaleev, you can set your matrix server up just in dozens of minutes.


    Distill steps to setup the matrix server from https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/README.md

    See Also

    Matrix AppService Bridges in TypeScript

    Matrix AppService Bridges in JavaScript


    This week I had a great talk with YC partner Eric @ericmigi, who is a serial entrepreneur and also a geek with technology. He uses Matrix a lot and almost integrated all the instance messanger to his Matrix.

    But, the matrix does not support Wechat yet. So we'd like to introduce a matrix-wechat bridge to implement the Wechat protocol, and fill the gap between Matrix and Wechat.

    @ericmigi provide some links that will help us to kick off a starter, hope we could make a workable POC soon, and any contribution will be welcome.

    1. homeserver install in 1 hr
    2. examples of puppet bridges

    — Huan, April 2019

    @tulir has very rich experiences with building the matrix bridges such as:

    1. A Matrix-Telegram hybrid puppeting/relaybot bridge
    2. A Matrix-WhatsApp puppeting bridge

    — Huan, May 2019

    Todo/Question List

    • [ ] How to get room list from the matrix homeserver from matrix-appservice-bridge ?
    • [ ] How to get members from a room from the homeserver matrix-appservice-bridge ?
    • [ ] Use Matrix Remote Room for linking WeChat Room with Matrix Room.



    v0.8 Mar 1, 2020

    Finished #13: [TypeScript] Add typing system to matrix-js-sdk and matrix-appservice-bridge.

    1. Code Refactoring
    2. Add !login, !logout command with help message
    3. Tested with iPad API(wechaty-puppet-padplus)

    v0.6 (Beta) Feb 25, 2020

    1. added docker-compose.yaml example. (thanks @ericmigi)
    2. Added install documentation

    v0.4 (Alpha) July 14, 2019

    1. Support receive/send Wechat message in Matrix. (individuals and rooms)
    2. Tested with Web API(wechaty-puppet-puppeteer) and iPad API(wechaty-puppet-padpro)

    Known Issues

    1. The names/avatars of Wechat users/groups are not set right on Matrix.
    2. Only support text message, Image/Audio/Video message is not supported yet. (Will be supported in the future version)
    3. Appservice will create more than one matrix room for a Wechat room when receiving messages from it for the very first time. (It will stop creating new rooms after you accepted the invitation)
    4. Login QR Code should not use the 3rd party API for security considerations. A better way is to upload the QR Code image to matrix server instead.

    v0.2 July 6, 2019

    1. Enable your matrix account to start using matrix-appservice-wechaty by talk to the bot @wechaty:your.domain
    2. After you talk to @wechaty, it will send you Wechat Login QR Code. Scan it to login Wechat
    3. All Wechat messages will be bridged to the Matrix system, in the room that you talk to the bot at the very first time.

    v0.0.1 May 2019

    1. Auto response the message in a Matrix Room.


    I accept no responsibility if Tencent ban your IP, Account or even your details on their system. They have never given official support on custom clients.

    — Credit: matrix-appservice-discord


    Huan (李卓桓) Tencent TVP of Chatbot, zixia@zixia.net

    Profile of Huan LI (李卓桓) on StackOverflow

    Copyright & License

    • Code & Docs © 2019-now Huan (李卓桓) zixia@zixia.net
    • Code released under the Apache-2.0 License
    • Docs released under Creative Commons


    npm i matrix-appservice-wechaty

    DownloadsWeekly Downloads






    Unpacked Size

    276 kB

    Total Files


    Last publish


    • avatar