# Variables Variables allow you to store data from API requests, action outputs, custom data and more. Variables can be used in almost every field of the actions and conditions [custom command and event builder](https://docs.botghost.com/custom-commands-and-events/command-and-event-builder). The **available** **variables** in your command-builder or event-builder may vary depending on the action, custom variables you have, API requests you use, and the event you might be using in case you are using the event builder. Here you may find some general information on what they are and how to use them.

## Targeting You can add a target to your variable to get data of a specific user, channel, role or server (more targeting options are available when using [#object-variables](#object-variables "mention")). To do so, add square brackets `[]` at the very end of your variable\*. Make sure to add a valid ID, variable or option. See below for more info. \* Targeting is slightly different for [object variables](#object-variables): the square brackets go before the first dot. For example, `{Channel[ID].name}` instead of `{Channel.name[ID]}`. ### Plain ID You can use a plain ID as a target. This means the variable will always return the value of the same user, channel or role. Below are some examples: * `{user_icon[136327647792726016]}` * `{user_joinedAt[136327647792726016]}` * `{channel_name[1021852614725480448]}` ### Options In custom commands you can use an option for your target (make sure it's a valid variable type: you need to use user options if you want to target a user using a option). The variable name should be inside your square brackets `[]`, without any curly brackets `{}` around it, and preceded by `option_`. Below are some examples: * `{user_icon[option_user]}` * `{user_joinedAt[option_player]}` * `{channel_name[option_channel]}` ### Variables Containing an ID Lastly, you can also use other variables that contain an ID. Unlike options, make sure to paste the full variable inside your square brackets `[]`, including the curly brackets `{}`. Below are some examples: * `{user_icon[{bot_id}]}` * `{user_joinedAt[{api.response.id}]}` * `{channel_name[{BGVAR_my_custom_variable}]}` ## Storing Custom Data ### Storing Data across all commands and events If you want to store data across all commands and events, you can use the [data storage](https://docs.botghost.com/custom-commands-and-events/data-storage#variable-types), which allows you to store and retrieve data with different types of variables. ### Storing Data in a command or event You can also store data only in a specific command / event execution, meaning that once the execution of the command / event is completed, saved data will be deleted. This is useful to easily store temporary data. Check out the [set-a-unique-variable](https://botghost.com/docs/custom-commands-and-events/actions/other-actions/set-a-unique-variable "mention") page to learn more. ## Variables ### Object Variables Some variables in BotGhost allow you to access properties of Discord objects, such as guilds, channels, or members, through dot notation. These variables start with a Capital letter and give you access to all the properties available on their respective Discord.js objects. For example, `{User[136327647792726016].username}` would return the username of the user with that ID. Dot notation allows you to access sub-objects of an object. For example, `{Message.channel.name}` will return the name of the channel the message was sent in. All properties and connections to other objects are described in the [discord.js](https://discord.js.org/docs/packages/discord.js/main) Documentation. You can view a list of all properties of an object through the variable selector (clipboard icon). Objects highlighted in green do not require you to provide an ID or a parameter for the object variable to work (for example, when you run a command the Guild object is automatically set to return information about the server the command was used in. You can however overwrite the pre-defined value with `[VALUE]`, as described above). Some object variables do not require a selector depending on the command or event type. For example, in a command, `{User.username}` would return the username of the user who ran the command. These are shown in green with the text "Available". All other objects require an ID to be specified.

Currently these objects are available:

Object Variable	Details	Example	Properties
Message	Access properties of a specific Discord message.	`{Message.author}`	Message Properties
Guild	Access properties of a guild.	`{Guild.memberCount}`	Guild Properties
Channel	Access properties of a channel.	`{Channel[1021852614725480448].url}`	Text Channel Properties Forum Channel Properties Thread Properties Media Channel Properties Announcement Channel Properties Voice Channel Properties Stage Channel Properties Category Properties
Member	Access properties of a server member.	`{Member[{option_user}].roles}`	Guild Member Properties
User	Access properties of a user.	`{User.createdTimestamp}`	User Properties
Role	Access properties of a role in a server.	`{Role[{option_role}].permissions}`	Role Properties
Invite	Access the properties of an invite.	`{Invite[{invite_code}].inviter}`	Invite Properties
Sticker	Access the properties of a sticker.	`{Sticker.name}`	Sticker Properties
AuditLogEntry	Access the properties of an audit log entry.	`{AuditLogEntry[{auditlogid.response.audit_log_entries.0.id}].actionType}`	Guild Audit Log Entry Properties
StageInstance	Access the properties of a stage Instance.	`{StageInstance.topic}`	Stage Instance Properties
AutoModerationRule	Access the properties of an AutoMod rule.	`{AutoModerationRule.triggerType}`	AutoModeration Rule Properties
AutoModerationActionExecution	Access the properties of an AutoMod action execution.	`{AutoModerationActionExecution.matchedContent}`	AutoModeration Action Execution Properties
Reaction	Access the properties of a reaction.	`{Reaction.count}`	Message Reaction Class
Emoji	Access the properties of a custom emoji.	`{Emoji[{Reaction.emoji}].createdTimestamp}`	Emoji Properties
GuildScheduledEvent	Access the properties of a guild scheduled event	`{GuildScheduledEvent[{option_event-id}].userCount}`	Guild Scheduled Event Properties
GuildBan	Access the properties of a ban.	`{GuildBan.reason}`	Guild Ban Properties
Presence	Access the properties of a user's presence.	`{Presence.status}`	Presence Properties
VoiceState	Access the properties of a voice channel's state.	`{VoiceState.selfMute}`	Voice State Properties

### Music Variables There are also some variables that allow for integration with the [music actions](https://botghost.com/docs/custom-commands-and-events/actions/music-actions). With these, you can do things like fetch information about the song or the player. #### Music Objects The following are object variables for music actions that are accessed the same way as described in the [Object Variables](#object-variables) section.

Object Variable	Details	Example	Properties
MusicPlayer	Access the properties of the server's music player.	`{MusicPlayer.current}`	Music Player Properties
MusicCurrentTrack	Access the properties of the currently playing track.	`{MusicCurrentTrack.author}`	Current Track Properties
MusicQueue	Access the properties of the music queue.	`{MusicQueue.tracks[0].title}`	Music Queue Properties
MusicSearchResult	Access the properties of a search from Search Tracks	`{MusicSearchResult[0].title}` `{MusicSearchResult.query}`	Search Result Properties

#### Music Variables The following variables can be used as-is, similar to [basic variables](#basic-variables). | Variable | Information | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `{music_search_formatted_list}` | Returns a nicely formatted list of all search results (numbered list with title, artist, and duration). | | `{music_search_status}` | Returns the status of the last search (success/no\_matches). | | `{music_search_results_length}` | Returns the number of results found. | | `{music_search_query}` | Returns the search query that was used. | | `{music_current_track_title}` | Returns the title of the currently playing track. | | `{music_current_track_author}` | Returns the author/artist of the currently playing track. | | `{music_current_track_url}` | Returns the URL of the currently playing track. | | `{music_current_track_requester}` | Returns the user ID of the user who requested the currently playing track. | | `{music_current_duration_formatted}` | Returns the duration of the currently playing track formatted as MM:SS or HH:MM:SS. | | `{music_current_duration_total}` | Returns the total duration of the current track in seconds. | | `{music_current_position_formatted}` | Returns the current position formatted as MM:SS. | | `{music_remaining_time_formatted}` | Returns the remaining time in the current track formatted as MM:SS. | | `{music_position_percentage}` | Returns the current position as a percentage of the total duration (0-100). | | `{music_position_formatted_with_duration}` | Returns the current position and total duration, formatted like '1:23/4:56\`. | | `{music_queue_length}` | Returns the number of tracks in the queue. | | `{music_queue_next_track}` | Returns the title of the next track in the queue. | | `{music_queue_next_track_author}` | Returns the author/artist of the next track in the queue. | | `{music_queue_total_duration_formatted}` | Returns the total duration of all tracks in the queue formatted as HH:MM:SS. | | `{music_queue_is_empty}` | Returns 'true' if the queue is empty, and 'false otherwise. | | `{music_queue_formatted_list}` | A nicely formatted numbered list of all tracks in the queue (title, artist, and duration). | | `{music_queue_list}` | An unformatted comma-separated list of track titles in the queue (e.g. Song1,Song2,Song3). | | `{music_search_results_list}` | Returns an unformatted comma-separated list of track titles from search results (e.g. Song1,Song2,Song3). | | `{music_is_playing}` | Returns 'true' if music is playing, and 'false' otherwise. | | `{music_is_paused}` | Returns 'true' if the music is paused, and 'false' otherwise. | | `{music_is_connected}` | Returns 'true' if the bot is connect to a voice channel, 'false' otherwise. | | `{music_is_ready}` | Returns 'true' if the music system is ready (i.e. connected to the lavalink node), 'false' otherwise. | | `{music_loop_mode_text}` | Returns 'Off', 'Track', or 'Queue' based on the loop mode. | | `{music_volume_percentage}` | Returns the current volume as a percentage (e.g. '50%'). | | `{music_autoplay_status}` | Returns 'Enabled' or 'Disabled' for autoplay. | | `{music_autoleave_status}` | Returns 'Enabled' or 'Disabled' for autoleave. | ### Collection / Array Variables BotGhost offers some variables you can use for any array or collection (even from an API response), which allow you to retrieve specific information of the collection.

Variable	Information
`{lowestValue({BGVAR_collection})}`	Returns the lowest value in a collection.
`{highestValue({BGVAR_collection})}`	Returns the highest numerical value in a collection.
`{lengthOfCollection({BGVAR_collection})}`	Returns the length of a collection.
`{valueAtPosition({BGVAR_collection}),[2]}`	Returns the value at a specific position in the collection. Positions start at 0.
`{positionOfValue({BGVAR_collection}),[hello]}`	Returns the position of a value.
`{collectionCharacterLength({BGVAR_collection})}`	Returns the total character length of a collection.
`{printAllValues({BGVAR_collection}),[Hello $value]}`	Prints all values in a collection. The text returned can be set in the []. Use `$value` to print the value, and `$index` to display the index of the value shown.
`{getRandomFromCollection({BGVAR_collection})}`	Returns a random value from the collection.

### Basic Variables Below are all basic variables that you can use in the [command or event builder](https://docs.botghost.com/custom-commands-and-events/command-and-event-builder).

Variable	Details	Supports Targets	Example Output
`{user}`	Returns the mention of the user	false	<@1085541861692813332>
`{server}`	Returns the server name	false	BotGhost👻
`{channel}`	Returns the mention of the channel	false	<#879733469452836864>
`{^ROLE NAME}`	Returns the mention of a role on role name	false	<@&1190298492661420163>
`{#CHANNEL NAME}`	Returns the mention of a channel on channel name	false	<#879733469452836864>
`{channel_name}`	Returns the name of the channel	true	general-chat
`{channel_type}`	Returns the type of the channel	true	GUILD_TEXT
`{channel_id}`	Returns the ID of the channel	false	879733469452836864
`{first_channel_id}`	Returns the first channel ID of the server	true	879733469452836864
`{server_members}`	Returns the server member count	true	12
`{server_icon}`	Returns a URL to the server icon	true
`{server_id}`	Returns the ID of the server	false	822426820447567872
`{server_owner}`	Returns the mention of the server owner	true	<@136327647792726016>
`{server_owner_id}`	Returns the ID of the server owner	true	136327647792726016
`{user_icon}`	Returns the icon of a user	true
`{user_name}`	Returns the user name of a user	true	tomtoise
`{user_id}`	Returns the ID of a user	true	136327647792726016
`{user_tag}`	Returns the user tag of a user	true	BotGhost Helper#4001
`{user_discriminator}`	Returns the discriminator of a user	true	#4001
`{user_createdAt}`	Returns the creation date of a user	true	Fri Apr 08 2022 13:51:34 GMT+0000 (Coordinated Universal Time)
`{user_joined}`	Returns the join date of the server from a user	true	Fri Apr 08 2022 13:51:34 GMT+0000 (Coordinated Universal Time)
`{user_displayName}`	Returns the display name of a user	true	Tomtoise
`{user_status}`	Returns the status of a user	true	online
`{random[min,max]}`	Returns a random number between min and max	false	6
`{isNumber(TEXT)}`	Checks if a string of text is a number	false	true
`{randomCharacters(3)}`	Returns a random set of numbers	false	hIVzhLgwIb
`{charCount(TEXT)}`	Returns the character count of a string of text	false	16
`{isBot}`	Checks if a user is a bot	true	true
`{bot_serverCount}`	Returns the server count of the bot	false	12
`{user_name_encoded}`	Returns a URL encoded version of a user name, useful when sending the user's name in API request's URLs	true	Tomtoise
`{time_now}`	Returns a timestamp of the current time	false	<t:1724181552:R>
`{time_ahead_h_HOURS}`	Returns a timestamp of a certain number of hours ahead	false	<t:1724181552:R>
`{time_ahead_m_MINS}`	Returns a timestamp of a certain number of minutes ahead	false	<t:1724181552:R>
`{time_now_unix}`	Returns a unix combination of the current time	false	1724181974
`{time_ahead_unix_h_HOURS}`	Returns a unix combination of a certain number of hours ahead	false	1724181974
`{time_ahead_unix_m_MINS}`	Returns a unix combination of a certain number of minutes ahead	false	1724181974
`{time_ahead_unix_s_SECS}`	Returns a unix combination of a certain number of seconds ahead	false	1724181974
`{encode_text[TEXT]}`	Returns url encoded text for API requests	false	Hello%2C%20how%20are%20you
`{ISO_to_UNIX[Timestamp]}`	Converts an ISO timestamp to an UNIX timestamp	false	1724181974
`{UNIX_to_ISO[Timestamp]}`	Converts an UNIX timestamp to an ISO timestamp	false	2024-02-26T20:28:40.902000+00:00
`{HEX_to_DECIMAL[HEX]}`	Converts a hex code to a decimal	false	1329119
`{solve_equation[1+1]}`	Solve a math equation	false	2
`{previous_numbers(10)}`	Returns all previous numbers of a given number	false	0, 1, 2, 3, 4, 5, 6, 7, 8, 9
`{numberWithCommas[1000000]}`	Formats large numbers with commas	false	1,000,000
`{numberWithDots[1000000]}`	Formats large numbers with dots	false	1.000.000
`{bot_id}`	Returns the ID of the bot	false	1085541861692813332
`{hasRole([ROLE_ARRAY])}`	Checks if the user has a set of roles	true	true
`{isChannel([CHANNEL_ARRAY])}`	Checks if the action is executed in a channel	true	true
`{subString(Hello World),[0,5]}`	Returns a substring of a given string	false	Hello
`{toUpperCase(hello)}`	Returns the given text to upper case	false	HELLO
`{escape_characters[TEXT]}`	Escapes the text provided to make it usable for API requests	false	Hello\nLine break
`{websocket_ping}`	Returns the ping of the bot	false	36 ms
`{interaction_id}`	Returns the ID of the interaction with the bot. This can be used in API requests to reply to interactions	false	1313779673350980230
`{interaction_custom_id}`	Returns the custom ID of the interaction with the bot (buttons/select menus)	false	A string of characters
`{interaction_token}`	Returns the token of the interaction with the bot. This can be used in API requests to reply to	false	A string of characters
`{ignoreVariables[{anotherVariable}]}`	Ignores all variables within the brackets `[]` and doesn't resolve them	false	{user}
`{null}`	Returns null (useful in comparison conditions)	false

### Error Variables Those variables can be used with the error handler block or success / error handles when something goes wrong with your tree. | Variable | Description | | ----------------- | ----------------------------------------------------------------------------- | | `{error_reason}` | Returns the reason why the error occurred. | | `{error_message}` | Returns the error message associated with the action the error occurred from. | | `{error_block}` | Returns name of the block which the error occurred in. | ### Other Variables

You can view all the available variables by checking the clipboard in the top right corner of a text input. This will open up a menu with a wide list of variables you can use in your command or event. The available variables in your command-builder or event-builder may vary depending on the action, custom variables you have, API requests you use, and the event you might be using in case you are using the event builder. | Variables | Details | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Event variables | Depending on what [event](https://docs.botghost.com/custom-commands-and-events/events) type you use, you will have an other set of basic variables that you can use to retrieve specific information of the event. Check out the [webhooks](https://botghost.com/docs/custom-commands-and-events/events/webhooks "mention") and [ifttt](https://botghost.com/docs/custom-commands-and-events/ifttt "mention")pages to know more about webhooks and IFTTT variables. | | Data storage variables | Depending on what [custom variables](https://docs.botghost.com/custom-commands-and-events/data-storage) you have created, you will have an other set of data storage variables. | | Form variables | Depending on what you name your [form actions](https://docs.botghost.com/custom-commands-and-events/actions/message-actions/send-a-form) have, you will have an other set of form response variables. | | API response variables | Depending on what API request you use, you will have an other set of [API response](https://docs.botghost.com/custom-commands-and-events/actions/api-actions/send-an-api-request) variables. | | Error handler variables | You can use a set of variables when your command or event triggers an error. You can use these variables to get, for example, the error reason. They can be used only below the "Error Handler" red block. | | Option variables | Depending on your [option](https://docs.botghost.com/custom-commands-and-events/options) names, you can have option variables in your command builder. | | Unique variables | Depending on the [unique variables](https://docs.botghost.com/custom-commands-and-events/actions/other-actions/set-a-unique-variable) that you use in your command or event and their names, you will have a set of unique variables. | | Success / error handler variables | You can use a set of variables when your action triggers an error. (If enabled) You can use these variables to get, for example, the error reason, message or action block. | | Loop variables | You can use a few variables inside of a [loop](https://docs.botghost.com/custom-commands-and-events/actions/loop-actions) to get the loop count (`{loop_count}`) and index (`{loop_index}`). | | Created channel variables | Depending on the name of a create a channel action, you can use a set of variables to get the channel name, ID and type. Check out the [create-a-channel](https://botghost.com/docs/custom-commands-and-events/actions/channel-actions/create-a-channel "mention") page for more. | | Created / edited thread variables | You can create a variable to retrieve the name, ID and more of the created / edited thread. Check out the [create-a-thread](https://botghost.com/docs/custom-commands-and-events/actions/thread-and-forum-actions/create-a-thread "mention") and [edit-a-thread](https://botghost.com/docs/custom-commands-and-events/actions/thread-and-forum-actions/edit-a-thread "mention") pages for more. | | Invite variables | You can use a set of variables to get the codes from a created invite link. Check out the [create-server-invite](https://botghost.com/docs/custom-commands-and-events/actions/server-actions/create-server-invite "mention") page for more. | | Manipulate some text variables | You can use a variable of a name of your choice to get the result of the [manipulate-some-text](https://botghost.com/docs/custom-commands-and-events/actions/other-actions/manipulate-some-text "mention") action. |