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.
- 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!
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
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:
You can restart synapse after this.
Finally, run the bridge!
node twitter-as.js -p 9000 -c config.yaml
- 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.
The key obtained by registering a new Twitter API application.
The secret obtained by registering a new Twitter API application.
- enable true/false
Should the bridge allow creation of new hashtag rooms.
- enable true/false
Should the bridge allow creation of new timeline rooms.
- 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.
- 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
- 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
#_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)
#_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.
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.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