Tags

Learn more about how SajuukBot can store generic, repeatable text in commands that can be called upon anytime via the Tags module.

SajuukBot will be ceasing operations on March 31st 2024, due to a variety of factors. For more information, please refer to the announcement provided on the SajuukBot discord server and your options for migrating to a new bot.

One of the common themes in certain types of communities, particularly those where people can get support or where a question is repeatedly asked with the same answer given, is how to automate that so people don't need to keep copy/pasting the same answer many times over.

Enter tags! This feature allows you to set up a static piece of text that can be updated by the creator and then others can use the requisite commands to retrieve that whenever its needed.

Tags has a supplementary feature available: Custom Tag Aliases. Please see the section on this for how to configure.

Configuration

This section of configuration is a root key, which means it should not be indented and in line with the basic settings like levels, prefix and the like. Please see the full basic configuration for more details on how it should be formatted.

tags:
  enabled: false
  commands:
    create:
      enabled: false
      level: 50
    update:
      enabled: false
      level: 50
    remove:
      enabled: false
      level: 50
    get:
      enabled: false
      level: 50
    list:
      enabled: false
      level: 50
    clear:
      enabled: false
      level: 100

Commands

Due to space constraints, the required syntax of commands, and an example of how they work, are given provided after the list of commands and explanations.

Every command follows the exact same formatting:

• A key called enabled determining if the command is enabled or not.

• A key called level, determining the minimum level required to use the command

At the root of the tags key is an enabled key, which globally controls the commands assigned to this module. If the root key is false, then no command will operate, regardless of whether an individual command is enabled.

All commands are subcommands to the !tag group.

Command	Description
!tag NAME_OF_A_TAG	Retrieves the contents of the named tag passed to the command. If the tag contents contains {member}, then passing a mention or ID of a member will have the resulting output contain a mention of the user: otherwise, it will mention the invoker.
!tag add	Creates a tag with the given name and content. Please note that, for anti-abuse reasons, certain content is automatically sanitised. You cannot create tags with names matching valid subcommands. If you want your command to contain a reference to a member, add {member} as it will be used as a placeholder to mention the member.
!tag update	Updates the content of a tag with the given name. Only the tag creator, or a user with a higher effective level than the creator, can update it.
!tag remove	Removes a named tag. As with updating, only the tag creator or a user with a higher effective level than the creator, can remove it.
!tag clear	Deletes all tags that were made for the guild. This operation is not reversible, and all tags will have to be remade if needed.
!tag list	Shows a list of all available tags created for the guild.

Syntax and Examples

Below are the syntax requirements of the above commands, along with an example to show how it works.

Syntax	Examples
!tag NAME_OF_THE_TAG	!tag some_tag !tag some_tag @SajuukBot#2980
!tag add TAG_NAME TAG_CONTENT	!tag add some_tag This is a message that will be sent if the tag is retrieved. !tag add some_tag Hey {member}, this is a message that will be sent if the tag is retrieved.
!tag update TAG_NAME TAG_CONTENT	!tag update some_tag This is a message that will be sent if the tag is retrieved. !tag update some_tag Hey {member}, this is a message that will be sent if the tag is retrieved.
!tag remove TAG_NAME	!tag remove some_tag
!tag clear	No arguments.
!tag list	No arguments.

Tag Aliases

The structure of the Tag Aliases feature in configurations is planned to be changed in the near future. More information will be provided on the SajuukBot support server nearer the time.

SajuukBot has a custom commands system which allows tags defined above to be given a "command like" alias. This allows for far easier reuse by members without needing to use the !tag get syntax in the chat.

To set up this feature, add a section to your configuration similar to the sample below:

custom commands:
  enabled: true
  commands:

Under the commands key, you need to pass a list of key value pairs representing the command that will bring back the named tag. An example can be seen below:

custom commands:
  enabled: true
  commands:
  - appeal: ["!banappeal", "!appeal", "?banappeal", "?appeal"]
  - report: ["!report", "?report", "/report"]

The name of each key must be a string representing the tag that is to be invoked when an alias is used. The value of a key should be a list containing strings: each string element of the list must represent a valid alias that will invoke the "key". Using the example above, if a user typed !appeal in the chat, and they had permission as described below, the bot would make a request internally to retrieve a tag called "appeal" and display the text associated to it.

Please note that tag aliases require that the user has permission to call the !tag get command as described before. If the user does not have permission, the alias will not respond to the user.