API Reference

class roleinvite.api.API(bot, config)[source]

Interact with RoleInvite from your cog.

To import the cog and use the functions, type this in your code:

roleinvite = bot.get_cog('RoleInvite').api


If roleinvite is None, the cog is not loaded/installed. You won’t be able to interact with the API at this point.


You can get the cog version by doing this

version = bot.get_cog('RoleInvite').__version__
coroutine add_invite(guild: discord.guild.Guild, invite: str, roles: list) → bool[source]

Add an invite link to the autorole system.

  • guild (discord.Guild) – The guild to get the invites from.
  • invite (str) – The invite link to create/extend. Give main or default if you want to edit the main/default autorole system.
  • roles (list) – A list of roles ID to add to the roles list.

True if successful

Return type:


  • NotInvite – The invite given is not a discord invite, not is is main/default.
  • CannotGetInvites – The bot doesn’t have the permission to get the guild’s invites
  • EmptyRolesList – The list of roles given is empty
  • InviteNotFound – The invite given doesn’t exist in the guild.

Return a Discord invite link that won’t show an embed

Parameters:text (str) – The text which needs to have invite links previews removes
Returns:text – The cleared text
Return type:str
coroutine get_invites(guild) → dict[source]

Return a list of the invites linked to the autorole system of the guild.

Parameters:guild (discord.Guild) – The guild to get the invites from.
Returns:A dict of invites linked to any role on the guild.


    "main" : {
        "roles" : [
    "" : {
        "roles" : [
        "uses" : 42
Return type:dict
coroutine remove_invite(guild: discord.guild.Guild, invite: str, roles: list = []) → bool[source]

Remove a list of roles from the invite links.

  • guild (discord.Guild) – The guild to get the invites from.
  • roles (list) – A : py:class:list of roles ID to remove from the roles list. If it’s empty, it will remove the invite from the autorole system.
  • invite (:py:class`str`) – The invite to remove roles from. Give Welcome to Red - Discord Bot’s documentation! or default to edit the main/default autorole system.

True if successful.

Return type:



KeyError – The invite given doesn’t exist.

coroutine update_invites() → dict[source]

Update all invites registered to keep their uses count good.

This is usually called on cog load since these values could have been modified while the bot or the cog was offline.

Returns:The updated dictionnary.


The value enabled may have been switched to False if the manage_guild permission was lost on the guild.

Return type:dict


Custom error handling used for the cog and the API

If you need to prevent and exception, do it like this

errors = bot.get_cog('RoleInvite').errors

    await api.add_invite(
        ctx.guild, 'main', [42]
except errors.CannotAddRole:
    print("Missing permissions")
except InviteNotFound:
    print("Invalid invite")
    # occurs for any exception
    print("Fatal error")
    # executed if the try succeeded
    print("All good")
    # always executed
    print("End of function")
exception roleinvite.errors.CannotAddRole[source]

The bot isn’t allowed to give a role. The role hierarchy was modified or a 3rd party module added the role without check.

exception roleinvite.errors.CannotGetInvites[source]

The bot isn’t allowed to get the guild invites. Manage server permission is needed.

exception roleinvite.errors.EmptyRolesList[source]

The list of roles that needs to be linked to an invite is empty.

exception roleinvite.errors.InviteNotFound[source]

The invite sent isn’t in the guild’s invite list.

exception roleinvite.errors.NotInvite[source]

The invite sent is not found as a discord.Invite object.