| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
Creating User Apps

# What are User Apps?

A user app is a bot (application) which can be attached to a user's profile via oauth, rather than being invited to a guild via oauth. This is a relatively new feature on Discord, and will allow you to have your bot to act like a utility for the user, so regardless of what guild they are in, or if they are in a DM with someone else, they have access to your bot's commands and can issue them, potentially letting all users in that guild, or all users in the DM, see the replies from your slash commands.

Warning
  Do not confuse User Apps with User Bots. User Apps are a new and very well supported feature, whereas User Bots means connecting a user's token as a bot, and is prohibited by the Discord TOS!

# Building the invite

To get started, you will need to configure your bot so that it will accept a user app invite. This is done via the discord developer portal.

Click on your bot in the list of bots, and then choose Installation from the left hand menu. You must enable User Install if it is not already enabled.

Drop down the choices for Install link and change this to Discord Provided Link. The second box should auto-fill with an invite link. Note that this invite link will likely only show the client_id value. For default install settings for User Install, choose the only possible option, applications.commands and for the Guild Install section, choose the scopes applications.commands and bot as at least the bare minimum. You should also set the permissions your bot will use if it is invited to a guild.

Note
  The permissions you pick in the Guild Install box only apply if your bot is invited to a guild, not for a user app!

If you have entered all the settings correctly the screen should look like the one below (except the Administrator permission - don't use this, enter actual permissions!):

# Inviting the application

You can now invite your bot to your profile. Follow the invite link at the top of the screen by clicking copy and pasting it into a web browser. You will be prompted to either add the bot to your profile, or to a guild, as shown below. Choose to add the bot to your profile:

You may be prompted to prove you are not a robot (you aren't a robot, right? 🤖). Afterwards, the bot will be successfully added to your profile:

# Creating the program

From this point on, right now, your bot will do nothing as you haven't added any code yet to make it operate as a user app. This comes next. Below is an example bot with one user application command.

There are several important things to note in this program:

- When adding a new slash command, you must use the dpp::slashcommand::set_interaction_contexts function to set where this command is visible. You can specify any one of three possible values to be added to the vector:
  - dpp::itc_guild: A standard slash command, visible in guild channels
  - dpp::itc_bot_dm: A standard slash command, accessible in DMs with the bot (this replaces the functionality of dpp::slashcommand::set_dm_permission)
  - dpp::itc_private_channel: A user application command, visible anywhere to the user who added it to their profile.
- When responding to the slash command, most things remain the same, except of course if you reply to a user app command most things relating to the guild will be uninitialised default values. This is because there is no guild to reference.
- You can use dpp::interaction::is_user_app_interaction() to determine if the interaction is initiated from a user app command, or a guild command. dpp::interaction::is_guild_interaction() does the inverse.
- Calling dpp::interaction::get_authorizing_integration_owner() with the parameter value dpp::ait_user_install will give you the dpp::snowflake ID of the user who has the app added to their profile, if a user is currently executing a user app command. If you call this function when not in a user app context, you will get an uninitialised snowflake value instead.

## Example Program

#include <dpp/dpp.h>
int main() {
dpp::cluster bot("token");
bot.on_log(dpp::utility::cout_logger());
bot.on_ready([&bot](const auto& event) {
if (dpp::run_once<struct boot_t>()) {
bot.global_bulk_command_create({
dpp::slashcommand("userapp", "Test user app command", bot.me.id)
.set_interaction_contexts({dpp::itc_guild, dpp::itc_bot_dm, dpp::itc_private_channel})
});
}
});
bot.register_command("userapp", [](const dpp::slashcommand_t& e) {
e.reply("This is the `/userapp` command." + std::string(
e.command.is_user_app_interaction() ?
" Executing as a user interaction owned by user: <@" + e.command.get_authorizing_integration_owner(dpp::ait_user_install).str() + ">" :
" Executing as a guild interaction on guild id " + e.command.guild_id.str()
));
});
bot.start(dpp::st_wait);
}
dpp::cluster
The cluster class represents a group of shards and a command queue for sending and receiving commands...
Definition cluster.h:89
dpp::interaction::guild_id
snowflake guild_id
Optional: the guild it was sent from.
Definition appcommand.h:1051
dpp::interaction::get_authorizing_integration_owner
dpp::snowflake get_authorizing_integration_owner(application_integration_types type) const
Get the user who installed the application for a given type.
dpp::interaction::is_user_app_interaction
bool is_user_app_interaction() const
Returns true if this interaction occurred as a user-app interaction, e.g. within a DM or group DM,...
dpp::slashcommand
Represents an application command, created by your bot either globally, or on a guild.
Definition appcommand.h:1449
dpp::slashcommand::set_interaction_contexts
slashcommand & set_interaction_contexts(std::vector< interaction_context_type > contexts)
Set the interaction contexts for the command.
dpp::snowflake::str
std::string str() const
Returns the stringified version of the snowflake value.
Definition snowflake.h:167
dpp::utility::cout_logger
std::function< void(const dpp::log_t &)> DPP_EXPORT cout_logger()
Get a default logger that outputs to std::cout. e.g.
dpp::ait_user_install
@ ait_user_install
Installable to users.
Definition integration.h:44
dpp::run_once
auto run_once()
Run some code within an if() statement only once.
Definition once.h:41
dpp::itc_guild
@ itc_guild
Interaction can be used within servers.
Definition appcommand.h:831
dpp::itc_bot_dm
@ itc_bot_dm
Interaction can be used within DMs with the app's bot user.
Definition appcommand.h:836
dpp::itc_private_channel
@ itc_private_channel
Interaction can be used within Group DMs and DMs other than the app's bot user.
Definition appcommand.h:841
dpp::st_wait
@ st_wait
Wait forever on a condition variable. The cluster will spawn threads for each shard and start() will ...
Definition cluster.h:72
dpp::interaction_create_t::reply
void reply(command_completion_event_t callback=utility::log_error()) const
Acknowledge interaction without displaying a message to the user, for use with button and select menu...
dpp::interaction_create_t::command
interaction command
command interaction
Definition dispatcher.h:789
dpp::slashcommand_t
User has issued a slash command.
Definition dispatcher.h:806

# Testing

If all goes to plan, your new command will be accessible everywhere!

D++ Library version 9.0.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0