> For the complete documentation index, see [llms.txt](https://docs.kickbot.com/dashboard/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kickbot.com/dashboard/api/reference/commands.md). # Custom commands KickBot API and MCP reference for Custom commands. Chat commands that reply with a configured message. Chat commands that reply with a configured message. MCP area name: `commands`. | Tool | REST | Access | | --------------------------------------------- | ------------------------------ | ------ | | [`list_commands`](#list-commands) | `GET /commands` | Read | | [`get_command`](#get-command) | `GET /commands/{id}` | Read | | [`create_command`](#create-command) | `POST /commands` | Write | | [`update_command`](#update-command) | `PATCH /commands/{id}` | Write | | [`set_command_by_name`](#set-command-by-name) | `PUT /commands/by-name/{name}` | Write | | [`delete_command`](#delete-command) | `DELETE /commands/{id}` | Write | ## list\_commands **List custom commands.** List all chat commands: custom ones and the built-in ones (built\_in = true, which can be edited and disabled but not renamed or deleted). `GET /api/v1/commands` No input fields. ## get\_command **Get a command.** Get one command by id. `GET /api/v1/commands/{id}` | Field | Type | Required | Description | | ------------------ | ------- | -------- | ------------ | | `id` (in the path) | integer | Yes | The item id. | ## create\_command **Create a custom command.** Create a custom chat command. Needs the Kick channel connected to KickBot. Use set\_command\_by\_name instead if the command may already exist. `POST /api/v1/commands` Needs a read and write key or connection. | Field | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. | | `response` | string | Yes | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request(" (text from a URL). | | `mod_only` | boolean | No | Moderators can use the command. | | `sub_only` | boolean | No | Subscribers can use the command. | | `vip_only` | boolean | No | VIPs can use the command. | | `everyone_only` | boolean | No | Everyone can use the command. Default true. | | `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). | | `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. | | `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. | ## update\_command **Update a command.** Change some fields of a command. Only the fields you send change. Built-in commands keep their name. `PATCH /api/v1/commands/{id}` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | No | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. | | `response` | string | No | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request(" (text from a URL). | | `mod_only` | boolean | No | Moderators can use the command. | | `sub_only` | boolean | No | Subscribers can use the command. | | `vip_only` | boolean | No | VIPs can use the command. | | `everyone_only` | boolean | No | Everyone can use the command. Default true. | | `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). | | `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. | | `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. | | `id` (in the path) | integer | Yes | The item id. | ## set\_command\_by\_name **Create or update a command by name.** Idempotent setup: if a command with this name exists, update it with the fields you send; if not, create it (unset fields use the defaults). Safe to run again. `PUT /api/v1/commands/by-name/{name}` Needs a read and write key or connection. | Field | Type | Required | Description | | -------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` (in the path) | string | Yes | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. | | `response` | string | No | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request(" (text from a URL). | | `mod_only` | boolean | No | Moderators can use the command. | | `sub_only` | boolean | No | Subscribers can use the command. | | `vip_only` | boolean | No | VIPs can use the command. | | `everyone_only` | boolean | No | Everyone can use the command. Default true. | | `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). | | `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. | | `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. | ## delete\_command **Delete a custom command.** Delete a custom command. Built-in commands cannot be deleted; disable them with update\_command. `DELETE /api/v1/commands/{id}` Needs a read and write key or connection. This cannot be undone. | Field | Type | Required | Description | | ------------------ | ------- | -------- | ------------ | | `id` (in the path) | integer | Yes | The item id. | ## Need help? Email or ask in the `#support` channel on [Discord](https://discord.gg/MAg3gBbc89). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.kickbot.com/dashboard/api/reference/commands.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.