Custom commands API

Use these actions to manage the chat commands that reply with a set message, for example !discord.

Each action is a REST endpoint under https://kickbot.com/api/v1 and an MCP tool with the same name. The MCP area name is commands. Use it to load only this area: https://kickbot.com/api/v1/mcp?areas=commands.

A team member needs the Custom commands permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See Permissions and security.

How the feature works in the dashboard: Custom commands, Command variables.

Actions

Tool	REST	Access
list_commands	GET /commands	Read
get_command	GET /commands/{id}	Read
create_command	POST /commands	Write
update_command	PATCH /commands/{id}	Write
set_command_by_name	PUT /commands/by-name/{name}	Write
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(“https://api.example.com”).value}} (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(“https://api.example.com”).value}} (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(“https://api.example.com”).value}} (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 can delete or replace data, and you may not be able to undo it.

Field	Type	Required	Description
id (in the path)	integer	Yes	The item id.