Fork me on GitHub

Twitter Bridge for Matrix

Interact with Twitter through your Matrix Client

About the Project

This project allows you to bridge Twitter accounts, timelines and hashtags to a Matrix homeserver (see more about that below).

You can use a Matrix as a Twitter client and send tweets through, or you can monitor a hashtag through any software that supports the matrix protocol.


Join the discussion on Matrix!


We expect you to be running a standard synapse setup for these instructions

The master release for this project is currently unsupported. While work is ongoing to release a version, #develop should be used.

Clone this repo and install the npm dependencies as usual.

    git clone
    git checkout develop
    npm install

You will need a twitter application authentication token and secret to continue.

Go to and create a new app. If you follow the setup all the way through you should be given all you need to fill in a config.yaml file. Copy config.sample.yaml and fill in the blanks before saving as config.yaml.

Next, we need to generate the appropriate registration config so that synapse can interface with the bridge.

    node twitter-as.js -r -u "URL"

The URL should be replaced by the domain/ip and port of the bridge. In this case you can usually leave it as http://localhost:9000 if you plan to run it on the same server as synapse and will be keeping the default port.

Copy/symlink the generated registration file to your synapse directory and finally edit your homeserver.yaml file for synapse so that the bridge is registered. This means changing app_service_config_files and inserting the name of your config file into the list. It should look similar to this:

    app_service_config_files: ["twitter-registration.yaml"]

You can restart synapse after this.

Finally, run the bridge!

    node twitter-as.js -p 9000 -c config.yaml


Using the bridge

Linking your Twitter account to your Matrix user

Linking is not required for reading timelines/hashtags, but interactions must be completed under your own account.

*type help for explanations on commands

User Timelines

Simply join #_twitter_@screennamegoeshere:yourdomain to read a users timeline. Protected timelines are not available.

Accounts which are bridged (Twitter<->Matrix) will be able to send tweets to these timelines (you do not need to put the @screen_name, it is done automatically)


Join #_twitter_#hashtaggoeshere to follow a particular hashtag.

Accounts which are bridged (Twitter<->Matrix) will be able to send tweets which will automatically apply this hashtag.

Direct Messages

Due to limitations in the Twitter API, group DMs are not possible.

On recieving a DM, you will be invited to a room where you can message each other as if it was another Matrix user.

Rejoining previous conversations is not possible, but either user sending a message will create a private room

This project was created as part of Google Summer of Code 2016 for

Matrix is an open standard for decentralised communication, providing simple HTTP APIs and open source reference implementations for securely distributing and persisting JSON over an open federation of servers.

You can learn more, including a list of compatible clients and how to run your own server here