https://github.com/yuuzi261/tweetcord
A Discord bot for Twitter notifications, using tweety-ns module.
https://github.com/yuuzi261/tweetcord
bot discord discord-bot discordbot python python3 tweety twitter twitter-api
Last synced: 2 months ago
JSON representation
A Discord bot for Twitter notifications, using tweety-ns module.
- Host: GitHub
- URL: https://github.com/yuuzi261/tweetcord
- Owner: Yuuzi261
- License: mit
- Created: 2023-09-19T15:03:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-09T18:09:54.000Z (2 months ago)
- Last Synced: 2025-04-09T21:13:39.299Z (2 months ago)
- Topics: bot, discord, discord-bot, discordbot, python, python3, tweety, twitter, twitter-api
- Language: Python
- Homepage:
- Size: 2.15 MB
- Stars: 67
- Watchers: 3
- Forks: 20
- Open Issues: 5
-
Metadata Files:
- Readme: docs/README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tweetcord
A Discord Bot for Twitter Notifications
[](https://www.python.org/downloads/)
[](https://github.com/Yuuzi261/Tweetcord/releases)
[](https://github.com/Yuuzi261/Tweetcord/releases)
[**English**](./README.md) | [**繁體中文**](./README_zh.md)
## 📝Introduction
Tweetcord is a Discord bot that leverages the [tweety-ns module](https://github.com/mahrtayyab/tweety) 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):
```plaintext
{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):
```plaintext
@Ping_SubTweet ﾅﾁｮﾈｺ just tweeted here:
https://twitter.com/nyachodayo/status/1869000108697960952
```
## 📥Installation
Before running the bot, you need to install the necessary modules.
```shell
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](./UPGRADE_GUIDE.md)
### 1. Create and configure the .env file
```env
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
```env
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?)](https://github.com/mahrtayyab/tweety/wiki/FAQs#twitter-new-limits), 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](#commands). |
### 3. Run and invite the bot to your server
```shell
python bot.py
```
🔧Bot Permissions Setup `2147666944`
- [x] Read Messages/View Channels
- [x] Send Messages
- [x] Embed Links
- [x] Attach Files
- [x] Mention Everyone
- [x] 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](https://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](https://freeserver.tw/index.html)
⚙️some configuration files you may need if you use fly.io
- dockerfile
```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
```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.
[](https://github.com/Yuuzi261/Tweetcord/graphs/contributors)
This project also benefits from the creative contributions of artists who provide our logo.
