Twitter Bridge for Matrix

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.

Features

• Read and follow a users timeline
• Send tweets from yourself and to other users.
• Follow hashtags.
• Direct messaging
• Read your own timeline

Join the discussion on Matrix!

Installation

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 https://github.com/Half-Shot/matrix-appservice-twitter
    git checkout develop
    npm install
		

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

Go to https://apps.twitter.com/ 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
		

config.yaml

• bridge
• domain http://localhost

  The homeserver's domain.

• homeserverUrl http://localhost:8448

  The homeservers URL.

• database_file twitter.db

  The file to store SQLITE data in.

• app_auth
• consumer_key

  The key obtained by registering a new Twitter API application.

• consumer_secret

  The secret obtained by registering a new Twitter API application.

• hashtags
• enable true/false

  Should the bridge allow creation of new hashtag rooms.

• timelines
• enable true/false

  Should the bridge allow creation of new timeline rooms.

• media
• enable_download true/false

  Should media inside tweets be uploaded to the homeserver, or just linked?

• enable_profile_images true/false

  Should profile images be set for twitter accounts.

• logging
• file logs/twitter-db.log

  The file to log to. Please make sure to create any directories.

• size 50m

  How big should files be before they are rotated. Use the suffix m for MB.

• count 3

  How many files should be kept before old ones are deleted

• compress true/false

  Compress files using gzip?

• level warn

  One of silent, error, warn, info, verbose, silly

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.

• Create a room and invite @_twitter_bot:yourdomain.
• Send the message account.link (read|write|dm) where the argument sets the requested permission level*.
• Follow the URL and instructions. Copy the PIN code
• Enter the pin code directly into the room and your account should be linked up.

*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)

Hashtags

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

Matrix.org

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

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