Crossgram

Repost Tweets to Telegram automatically. Built by Levellr.

Crossgram is a TypeScript library and web service you can use to automatically repost Tweets to Telegram chats, groups, supergroups or channels using a Telegram Bot.

You can:

• Follow one Twitter account or many
• Reposts tweets into one Telegram chat or many
• Use a single Telegram bot, or use a different bot for each chat

A single Crossgram instance even can be used to stream Tweets from multiple accounts to multiple Telegram chats using multiple Telegram bots. For example, one Crossgram instance can repost:

• Tweets from @city_xtra to the Manchester City - City Xtra supergroup via the "City Xtra on Twitter" bot
• Tweets from @theanfieldwrap to the Liverpool Football Club - The Anfield Wrap supergroup via the "The Anfield Wrap on Twitter" bot
• Tweets from @bbcnews and @guardiannews to the UK News Tweets channel via the "UK News on Twitter" bot

Twitter shortlinks are automatically expanded — no more mysterious 't.co' links in your chat!

Need a no-code solution? 👷

If you don't code and you just want a bot to automatically repost Tweets from Twitter to Telegram for you, we're running a closed beta that can help you out.

Drop us a line and tell us about your Telegram community to find out if you're eligible to join.

Getting started

To get started, you'll need:

• A Twitter API project, and specifically the consumer key and consumer secret from that project.
• A Telegram Bot, which can be created using @BotFather
• The Telegram chat ID for your channel, group or supergroup. See https://stackoverflow.com/questions/33858927/how-to-obtain-the-chat-id-of-a-private-telegram-channel for a guide on easily finding this ID.

Remember to add the bot to the channel, group or supergroup with permission to post content.

Running Crossgram

Clone the project:

  git clone https://github.com/levellr/crossgram.git

Go to the project directory:

  cd crossgram

Install dependencies:

  npm install

Start the script:

  npm run start

Deploying Crossgram

Use a platform of your choice, or deploy in one click:

Configuration

The web service (via npm run start or bin/stream.ts) is configured using environment variables.

The following environment variables are required, and the script will not start without them:

| Environment variable | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | TELEGRAM_BOT_TOKENS | A comma-separated list of bot tokens for Telegram bots created via @BotFather | | TELEGRAM_CHAT_IDS | A comma-separated list of Telegram chat IDs to which the Tweets should be posted | | TWITTER_USERNAMES | A comma-separated list of Twitter usernames to watch and repost to Telegram | | TWITTER_CONSUMER_KEY | The consumer key for a Twitter API client | | TWITTER_CONSUMER_SECRET | The consumer secret for a Twitter API client |

The environment variable TELEGRAM_CHAT_IDS must contain either exactly one value or exactly as many values as there are TWITTER_USERNAMES.

• If there is one chat ID, all tweets from all usernames in TWITTER_USERNAMES will be streamed to the specified chat ID.
• If there are multiple chat IDs, the script will iterate through TELEGRAM_CHAT_IDS AND TWITTER_USERNAMES in a pairwise fashion. It will stream tweets from the first username to the first chat ID, the second username to the second chat ID, etc.

The environment variable TELEGRAM_BOT_TOKENS must contain either exactly one value or exactly as many values as there are TELEGRAM_CHAT_IDS.

• If there is one bot token, tweets destined for all chat IDs will be sent via the specified bot token.
• If there are multiple chat IDs, the script will iterate through TELEGRAM_BOT_TOKENS AND TELEGRAM_CHAT_IDS in a pairwise fashion. It will send tweets to the first chat ID using the first bot token, to the second chat ID using the second bot token, etc.

Neither chat IDs or bot tokens have to be unique.

If specified in a .env file in the root of the project, environment variables will be automatically loaded at app start.

Using Crossgram as a library

Install Crossgram with npm:

  npm install @levellr/crossgram

Then use the library:

const { TwitterStreamer } = require('@levellr/crossgram');

async function main() {
  console.log('Starting Twitter API client');

  const streamer = await TwitterStreamer.create({
    twitterAppKey: 'TWITTER_CONSUMER_KEY',
    twitterAppSecret: 'TWITTER_CONSUMER_SECRET',
  });

  // Register a stream from Twitter to Telegram
  console.log(`Registering stream`);
  await streamer.registerStream({
    twitterUsername: 'TWITTER_USERNAME',
    telegramBotToken: 'TELEGRAM_BOT_TOKEN',
    telegramChatId: 'TELEGRAM_CHAT_ID',
  });
}

main();

You can also use module imports:

import { TwitterStreamer } from '@levellr/crossgram';

Testing

  npm run test

Code formatting and linting

# code linting with eslint
$ npm run lint

# formating with Prettier
$ npm run format

Contributing

Contributions welcome! Please start with an issue before making a pull request so we can make sure we're all on the same page.

Check out our contribution guidelines for this project for more information.

License

Crossgram is open-source under the GNU Affero General Public License Version 3 (AGPLv3).