# Event variables

> The ready-made variables your code gets in each kind of command and event.

Your code starts with some variables already filled in, like `user` and `server`. Which ones you get depends on what started the code.

The tables below list them. Using a variable that is not in the list fails with a "not defined" error. All helper functions in the API reference are there too, unless a section says otherwise.

To read what is on each object, see [Objects](https://ccbot.app/docs/reference/objects).

## Slash command

| Variable | What it is |
|---|---|
| `user` | The member who ran the command. |
| `channel` | The channel it ran in. |
| `server` | The server. |
| `interaction` | The slash command interaction. |
| `command_name` | The command name. |
| `unix_timestamp` | The current time as a Unix number. |
| `variables` | Your saved server variables. |
| Each option | Every option, under its own name. An option `amount` is the variable `amount`. |

Only in the post-hook, after the reply is sent:

| Variable | What it is |
|---|---|
| `response` | The reply message. |
| `response_dm` | The DM reply, when the reply went to DMs. |
| `response_feedback` | The short "Command executed" note, when the reply went to DMs or another channel. |
| `view` | Your View, after it finished. |
| `pre_hook_failed` | `True` when the pre-hook stopped with an error. |
| `pre_hook_cooldown` | `True` when a cooldown stopped the command. |
| `pre_hook_error` | The pre-hook's error, if any. |

> **Options win:** An option named `user` replaces the `user` variable. Name options so they do not clash, like `target` instead of `user`.

See [How commands run](https://ccbot.app/docs/getting-started/how-commands-run) for the order of pre-hook, reply and post-hook.

## Text command

The same as a slash command, with two changes:

- `message` is the message that ran the command. There is no `interaction`.
- Saved variables load first, so a built-in name wins over a variable with the same name.

See [Text commands](https://ccbot.app/docs/getting-started/text-commands).

## Member Join, Leave and Update

| Variable | What it is |
|---|---|
| `user` | The member. |
| `server` | The server. |
| `event` | The raw Discord event. |
| `unix_timestamp` | The current time. |
| `old_user` | The member before the change. Leave and Update only. |
| `added_role` | The role ID, or list of IDs, that was added. Update only. |
| `removed_role` | The role ID, or list of IDs, that was removed. Update only. |

There is no `channel` and no `message`. `message_id` and `channel_id` are `None`.

## Message

Runs for every new message. **Premium only.**

| Variable | What it is |
|---|---|
| `user` | The author. |
| `message` | The message. |
| `channel` | Where it was sent. |
| `message_id`, `channel_id` | Their IDs. |
| `server`, `event`, `unix_timestamp` | As above. |

> **Skip bots first:** This event also runs for bot messages, your own bot's too. Start with a check, or your bot can answer itself forever:
> 
> ```python
> if user is None or user.is_bot:
>     return
> ```

## Reaction

Runs when someone adds or removes one of the emojis you list on the event.

| Variable | What it is |
|---|---|
| `user` | Who reacted. |
| `channel` | The channel. |
| `emoji_name` | The emoji, or the custom emoji's name. |
| `emoji_id` | The custom emoji's ID. `None` for normal emojis. |
| `action` | `"add"` or `"remove"`. |
| `message_id`, `channel_id` | The message and its channel. |
| `server`, `event`, `unix_timestamp` | As above. |

There is no `message` object. Get it with `get_message(channel_id, message_id)`.

## Voice Join, Leave and Change

| Variable | What it is |
|---|---|
| `user` | The member. |
| `channel` | The channel they joined. On Leave, the channel they left. |
| `old_channel` | The channel before. `None` on a fresh join. |
| `server`, `event`, `unix_timestamp` | As above. |

> **Note:** Voice Join also runs when someone moves between channels. Check `old_channel is None` to know it was a fresh join.

## Thread

Runs when a thread is made, changed or deleted.

| Variable | What it is |
|---|---|
| `channel`, `thread` | The thread. |
| `action` | `"create"`, `"update"` or `"delete"`. |
| `user` | The thread owner. `None` on delete. |
| `parent_id` | The channel the thread is in. |
| `thread_id` | The thread ID. |
| `event` | The raw Discord event. |

There is no `server` here. Use `event.get_guild()`.

## Clock

Runs when a clock or a repeating job fires. See [Scheduling](https://ccbot.app/docs/reference/scheduling).

| Variable | What it is |
|---|---|
| `custom_id` | The clock or job name. |
| `metadata` | The data you gave when you set it. |
| `server`, `event`, `unix_timestamp` | As above. |

In the event's custom IDs, list exact names, or end with `*` to match many, like `remind_*`.

## Vote (top.gg)

Runs when someone votes for your server on top.gg.

| Variable | What it is |
|---|---|
| `user` | The voter. `None` when they left the server. |
| `user_id` | The voter's ID. Always set. |
| `weekend` | `True` for a double-value weekend vote. |
| `vote_count` | The server's total votes, this one included. |
| `server`, `event`, `unix_timestamp` | As above. |

## Button Click / Select Menu Change

Runs when someone clicks a saved button or picks from a saved menu. List the component IDs on the event.

| Variable | What it is |
|---|---|
| `interaction` | The click. `interaction.values` holds menu picks. |
| `user` | Who clicked. |
| `custom_id` | Which button or menu. |
| `message` | The message the button is on. |
| `channel` | The channel. |
| `message_id`, `channel_id` | Their IDs. |
| `server`, `unix_timestamp` | As above. |

Also here: `defer_response`, `respond_interaction`, `send_modal`, `cooldown`, `require_permission`, `allowed_roles`, `banned_roles`, `allowed_channels`, `banned_channels`.

> **Answer within 3 seconds:** Call `defer_response()` first, then `respond_interaction(...)`. Or open a form with `await send_modal(form)` as the first answer. See [Interactions](https://ccbot.app/docs/reference/interactions).

## Modal Submit

Runs when someone sends a form. The event's custom IDs list the form IDs.

| Variable | What it is |
|---|---|
| `interaction` | The submit. |
| `user` | Who sent it. |
| `custom_id` | The form ID. |
| `values` | A dict of each field's ID to what they typed. |
| `channel`, `channel_id` | The channel. |
| `server`, `unix_timestamp` | As above. |

```python
answer = values.get("reason", "")
```

There is no `message`. The same 3-second rule and helpers as button clicks apply. See [Forms](https://ccbot.app/docs/concepts/forms).

## Autocomplete

Runs while someone types into a command option that has autocomplete. You return the suggestions.

| Variable | What it is |
|---|---|
| `interaction` | The autocomplete request. |
| `option` | The option being typed. `option.value` is the text so far. |
| `server`, `channel_id`, `unix_timestamp` | As above. |

There is no `user`. Reply in under 3 seconds with `respond_options`. Write `await` yourself.

```python
await respond_options(options, auto_filter=True)
```

| Argument | What it does |
|---|---|
| `options` | A list of text, or of `AutocompleteChoice(name=..., value=...)`. Only 25 show. |
| `auto_filter` | `True` keeps only choices that contain what was typed. |

```python
await respond_options([
    AutocompleteChoice(name="Red team", value="red"),
    AutocompleteChoice(name="Blue team", value="blue"),
])
```

`name` is what people see. `value` is what your command gets. Do not `fetch` or `sleep` here: it is too slow.