Tweetcord

A Discord Bot for Twitter Notifications

English | 繁體中文

📝Introduction

Tweetcord is a Discord bot that leverages the tweety-ns module to provide real-time tweet updates from specific Twitter users directly to your Discord server. Simply configure the Twitter users and Discord channels you want to monitor, and Tweetcord will automatically forward tweets to the designated channels, ensuring you never miss important updates.🐦

✨Features

Screenshots

👇Whenever a followed user posts a new tweet, your server will receive an instant notification.

Commands

👉 /add notifier username channel | mention type media_type account_used

Parameter	Type	Description
username	str	The username of the twitter user you want to turn on notifications for
channel	discord.TextChannel	The channel to which the bot delivers notifications
mention	discord.Role	The role to mention when notifying
type	str	Whether to enable notifications for retweets & quotes
media_type	str	Whether to enable notifications that include media, or only enable notifications that include media
account_used	str	The twitter client used by the bot to monitor the user's tweets

👉 /remove notifier username channel

Parameter	Type	Description
username	str	The username of the twitter user you want to turn off notifications for
channel	discord.TextChannel	The channel which set to delivers notifications

👉 /list users

• List all twitter users whose notifications are enabled on the current server

👉 /sync

• Sync the notification of new Twitter account with database. If you change the twitter account used by bot, please use this command

👉 /customize message username channel | default

Parameter	Type	Description
username	str	The username of the twitter user you want to set customized message
channel	discord.TextChannel	The channel which set to delivers notifications
default	bool	Whether to use default setting (default is false)

Custom notification messages are in f-string format, currently supporting 4 special variables for use, which will be explained below.

• {action} : poster's action, include tweeted, retweeted and quoted
• {author} : poster's display name
• {mention} : the role to mention when sending to discord
• {url} : the link of the tweet

Using the default notification as an example, if the message is customized to the following format (supporting Discord's markdown format):

{mention}**{author}** just {action} here: 
{url}

The notification will be sent in this format when a tweet is posted (here is a real-world example):

@Ping_SubTweet ﾅﾁｮﾈｺ just tweeted here: 
https://twitter.com/nyachodayo/status/1869000108697960952

📥Installation

Before running the bot, you need to install the necessary modules.

pip install -r requirements.txt

⚡Usage

📢This tutorial applies to version 0.5 or higher. For settings of older versions, please refer to the README files of the respective historical versions.

⬆️View Version Upgrade Guides

1. Create and configure the .env file

BOT_TOKEN=YourDiscordBotToken
TWITTER_TOKEN=NameForYourTwitterToken:YourTwitterAccountAuthToken
DATA_PATH=./data

Note

The NameForYourTwitterToken here can be freely defined. It is only used as an alias to specify the account when entering commands and does not need to match the Twitter account name.

Example

BOT_TOKEN=FAKE1234567890ABCDEFGHIJKLMNO.PQRSTUVWXYZ1234567890.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
TWITTER_TOKEN=Account1:12345abcde67890fghij12345klmnop67890qrstuv,Account2:abcdef123456ghijkl7890mnopqrst123456uvwx
DATA_PATH=./data

You can retrieve your auth token from cookies, or you can explore other methods to obtain it.

2. Configure the configs.yml file

Create configs.yml and copy the contents of configs.example.yml into it, and edit it to your liking.

Important

All configuration instructions here are synchronized with the latest version. For users of the old version, please refer to the old README.

Base

Parameter	Description	Restriction
prefix	The prefix for bot commands, only effective for prefix commands.	None, but recommended to choose a simple and easily identifiable prefix and avoid using empty strings.
activity_name	The activity name displayed by the bot.	None.
activity_type	The activity type displayed by the bot.	playing, streaming, listening, watching and competing only.
users_list_pagination_size	list users command's pagination size.	Only accepts integers, and it is not recommended to use too large or too small values.
users_list_page_counter_position	list users command's pagination counter position.	title and footer only.

Custom activity name is in f-string format, currently supporting 1 special variable for use, which will be explained below.

• {count} : the number of users currently being monitored, it will be updated in real time

Timer & Counter

Parameter	Description	Unit
tweets_check_period	The check frequency for the posts, it is not recommended to set this value too low to avoid rate limiting. Default value: 10, Safety value: 18 (why is this value?), not recommended below 10. If the account controlled by Tweetocrd is the same as the account you usually use, please increase the value appropriately to avoid rate limiting.	seconds
tweets_updater_retry_delay	Retry Interval when Tweets Updater encounters exceptions.	minutes
tasks_monitor_check_period	Interval at which to check if each tasks is functioning properly, and if a task has stopped, attempt a restart.	minutes
tasks_monitor_log_period	Interval at which to output the list of currently running tasks to the execution log.	hours
auth_max_attempts	The maximum number of attempts to log in to the Twitter account, if the number of failures exceeds this number, the bot will be forced to stop running.	times

Control Account Behavior

Parameter	Description
auto_change_client	If a new client is specified for an exisiting user, automatically use the new client to monitor the user.
auto_turn_off_notification	If all notifications for a user are disabled, decide whether to unfollow the user.
auto_unfollow	If all notifications for a user is disabled, decide whether to disable notification for the user (twitter side).

Database

Parameter	Description
auto_repair_mismatched_clients	Whether the system should automatically use the first client defined in the current environment variables to replace invalid client_used values in the database when they are not defined in the environment variables.

Embed Style

Parameter	Description
type	Determine the type of embed, supported types: built_in / fx_twitter.

built_in:

Parameter	Description
fx_image	Whether to use FxTwitter's combined image when there are multiple images, friendly for iOS systems that cannot display multiple image embeddings.
video_link_button	coming soon
footer_logo	coming soon

fx_twitter:

Parameter	Description
domain_name	The domain name to be used when sending tweet links, can be fxtwitter or fixupx.
original_url_button	coming soon

Message

Parameter	Description
default_message	Set default message format globally, the format is the same as the customized message, use f-string and support 4 special variables. For details, please refer to Commands.

3. Run and invite the bot to your server

python bot.py

🔧Bot Permissions Setup 2147666944

• Read Messages/View Channels
• Send Messages
• Embed Links
• Attach Files
• Mention Everyone
• Use Slash Commands

Note

If you want to host the bot on a server, here is a recommended service that is basically free: fly.io (update: fly.io has stopped offering free plans to new users)

Tip

Alternatively, you can try this virtual hosting service provided by Taiwanese students: FreeServer

⚙️some configuration files you may need if you use fly.io

• dockerfile

FROM python:3.11.11
WORKDIR /bot
COPY requirements.txt /bot/
RUN pip install -r requirements.txt
COPY . /bot/
CMD python bot.py

• fly.toml

app = "YOUR_APP_NAME"
primary_region = "YOUR_APP_REGION"

[env]
  DATA_PATH = "/data"

[mounts]
  source = "YOUR_APP_VOLUME_NAME"
  destination = "/data"

4. Have fun

Now you can go back to Discord and use the /add notifier command to set up notifications for the Twitter users you wish to receive updates from!

💪Contributors

This project exists thanks to all the people who contribute.

This project also benefits from the creative contributions of artists who provide our logo.