Skip to content

Latest commit

 

History

History
247 lines (165 loc) · 9.14 KB

README.md

File metadata and controls

247 lines (165 loc) · 9.14 KB
Raw

LOGO

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

📥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

Example

BOT_TOKEN=FAKE1234567890ABCDEFGHIJKLMNO.PQRSTUVWXYZ1234567890.ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
TWITTER_TOKEN=MyTwitterToken:12345abcde67890fghij12345klmnop67890qrstuv,MyTwitterToken2: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.

Custom activity message 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

Timer

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

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
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.10.9
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.

LOGO