> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tweet-catcher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord bot

> Create, start, and stop tasks from your Discord server with slash or text commands

The Tweet Catcher bot lets people in your Discord server manage your tasks without opening the dashboard. You choose which roles may use it, and every command acts on the tasks of the membership that whitelisted the role

> [!NOTE]
>
> To whitelist a role, your Discord account must be linked to an active Tweet Catcher or Whop membership. The people who use the bot afterwards only need the role

## Set up the bot

**1. Invite the bot**

Open the [invite link](https://discord.com/oauth2/authorize?client_id=1226671562795515984\&permissions=536873984\&scope=bot+applications.commands) and pick your server. You need the **Manage Server** permission on it

**2. Whitelist a role**

From the Discord account linked to your membership, run:

```text theme={null}
/role add role:@Monitors
```

The bot will reply with **Role Whitelisted**

**3. Give the role to your members**

Anyone with the role can now run task commands. Everyone else gets **Not Whitelisted**

## Manage roles

| Command | Effect |
| - | - |
| `/role list` | Show the roles you whitelisted, with their IDs |
| `/role add role:` | Whitelist a role |
| `/role remove` | Remove a role you whitelisted. Pass `role` to select it, or `id` with the ID from `/role list` |
| `/role clear` | Remove every whitelisted role on this server, whoever added it. Pass `role` to remove only that one. Requires **Manage Server** |

> [!TIP]
>
> Use `/role clear` as a server admin to remove a role whitelisted by someone who no longer has access to their account

## Slash commands

### Create a task

`/task add twitter` creates a Twitter task:

| Option | Required | Values |
| - | :-: | - |
| `user` | Yes | Handle without `@`, up to 16 characters |
| `options` | Yes | `Tweets only`, `All Posts`, `Following only`, `Posts and Following`, `User Updates only`, `Posts and User Updates`, `Following and User Updates`, `All Notifications` |
| `channel` | Yes | Text channel that receives the alerts |
| `ocr` | No | Read the text in images. Only applies when the task tracks posts |
| `role` | No | Role to mention. Pick `@everyone` to ping everyone |
| `start` | No | Start the task right away. Otherwise it is saved stopped |

`/task add truth` creates a Truth Social task. It takes the same `user`, `channel`, `role`, and `start` options, and these `options`: Posts only, Posts and Retweets, Posts and Replies, All Notifications

If a task for the same handle already exists, the bot asks whether to create another one

### Control tasks

| Command | Effect |
| - | - |
| `/task list` | Show your tasks with their ID, platform, options, and whether they are running. Pass `channel` to show only the tasks that post there |
| `/task start` | Start a task |
| `/task stop` | Stop a task |
| `/task delete` | Delete a task |

`start`, `stop`, and `delete` take either `user` or `id`. If several tasks match the handle, the bot ask for the specific one

### Username history

`/user history username:` lists the previous handles the monitor has seen for an account, with the date each one was detected. Coverage starts from when the monitor first saw the account, so it is not a complete rename history

## Text commands

Text commands are a faster way to add Twitter tasks. The prefix is `$` unless you change **Bot Prefix** in [Settings](https://docs.tweet-catcher.com/monitor/settings.md#discord). Type `$monitor help` to see this list in Discord

| Command | Effect |
| - | - |
| `$monitor list` | Show the tasks that post in the current channel |
| `$monitor add elonmusk` | Create and start a task in the current channel |
| `$monitor add elonmusk #alerts` | Create and start a task in `#alerts` |
| `$monitor add elonmusk,spacex,tesla` | Add several handles at once, separated by commas without spaces |
| `$monitor remove elonmusk` | Delete the task. Several handles can be comma-separated |
| `$monitor edit elonmusk status` | Show which options are on |
| `$monitor edit elonmusk replies off` | Turn one option off |
| `$monitor edit elonmusk ocr on` | Turn one option on |

Options you can edit: `posts`, `retweets`, `replies`, `following`, `userUpdates`, `ocr`

> [!TIP]
>
> Modify **Default Options** in [Settings](https://docs.tweet-catcher.com/monitor/settings.md#discord) to use personalized tasks options. Without defaults, they track posts, retweets, replies, following, and user updates, with no ping

## Troubleshooting

> [accordion] The bot replies Not Whitelisted
>
> You don't have a whitelisted role on this server. Ask the membership owner to run `/role add` for one of your roles, or to give you the whitelisted role

> [accordion] /role add returns a Command Error
>
> The Discord account running the command is not linked to an active membership. Run it from the account you use to sign in to Tweet Catcher or Whop

> [accordion] Failed to create or find the webhook
>
> The bot is missing **Manage Webhooks** in that channel, or the channel already has the maximum number of webhooks. Fix the permission or delete an unused webhook, then try again

> [accordion] The bot doesn't answer text commands
>
> Check that you are using the prefix set in **Bot Prefix**, and that the bot have the permissions to read and send messages in that channel. Slash commands keep working either way

> [accordion] No task found for the given user
>
> The handle must match the task exactly. Run `/task list` and use the handle as shown, or pass the task `id` instead

> [accordion] Limit of running tasks reached
>
> Your plan has no free running slots. Stop another task first, or see [Plans](https://docs.tweet-catcher.com/plans.md#extra-tasks) for more


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.