Chat commands

With the commands:manage scope, your app can list, create, edit and remove a channel's chat commands: the !name replies Xive posts for the creator when a viewer types one.

These are the same commands the creator manages in their studio, so anything your app adds shows up there too and the creator can change it.

Want your bot to answer a command itself? You don't need this scope. Read chat with chat:read, spot the command, and reply with chat:write. Use commands:manage when the reply is fixed text Xive can post on its own, even while your app is offline.

A command

{
  "id": "6c2f8a1d-0b4e-4d73-9e15-3a7c2b9f0d64",
  "name": "discord",
  "response": "Join the community: https://discord.gg/example",
  "cooldown_sec": 15,
  "is_active": true,
  "use_count": 27,
  "min_role": "anyone"
}

Field	Notes
`name`	Up to 32 letters, numbers, `_` and `-`, without the `!` (a leading `!` is stripped). Viewers type `!name`. Unique among the channel's active commands, ignoring case.
`response`	1 – 400 characters. Can use variables (below). Checked by the content filter.
`cooldown_sec`	0 – 3600. Default 15.
`min_role`	Who can use it: `anyone` (default), `follower`, `subscriber`, `vip`, `mod` or `broadcaster`.
`is_active`	`false` once retired.
`use_count`	How many times it has fired. Read-only.

Variables

The same syntax as Lumia Stream and Nightbot, so existing command libraries paste in unchanged. Double braces are standard; single braces work too.

Variable	Becomes
`{{username}}` / `{{user}}`	The display name of whoever typed the command.
`{{target}}` / `{{touser}}`	The first word after the command (a leading `@` removed), or the sender if there isn't one.
`{{message}}` / `{{args}}`	Everything after the command word.
`{{count}}`	How many times the command has fired, including this time.
`{{random=1-100}}`	A whole number in that range.

List commands

GET /api/apps/channels/{channelId}/commands returns every command, active ones first, plus the channel's limit.

{
  "success": true,
  "commands": [ { "id": "…", "name": "discord", "response": "…", "cooldown_sec": 15, "is_active": true, "use_count": 27, "min_role": "anyone" } ],
  "prefix": "!",
  "response_max": 400,
  "roles": ["anyone", "follower", "subscriber", "vip", "mod", "broadcaster"],
  "limit": 5,
  "limit_pro": 40
}

limit is how many active commands the channel can have: 5 on a free channel, 40 with Pro.

Create a command

POST /api/apps/channels/{channelId}/commands with name and response, and optionally cooldown_sec and min_role. Answers 201 with the new command.

curl -X POST https://api.thexive.com/api/apps/channels/CHANNEL_ID/commands \
  -H "Authorization: Bearer $XIVE_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "hug", "response": "{{user}} gives {{target}} a big hug 🤗", "cooldown_sec": 5}'

409 if the channel already has an active command with that name, or is at its limit (the body then has "pro_required": true on a free channel).

Edit a command

PATCH /api/apps/channels/{channelId}/commands/{commandId} with any of name, response, cooldown_sec, min_role and is_active. Fields you leave out don't change. Answers with the updated command.

curl -X PATCH https://api.thexive.com/api/apps/channels/CHANNEL_ID/commands/COMMAND_ID \
  -H "Authorization: Bearer $XIVE_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"min_role": "subscriber"}'

Remove a command

DELETE /api/apps/channels/{channelId}/commands/{commandId} retires it: it stops answering and its name is free again, but it stays in the list with is_active: false, so the creator can bring it back with PATCH {"is_active": true}.

Good practice

Don't overwrite or retire commands your app didn't create unless the creator asked it to. Keep track of the ids your app made.
Check limit before creating, so you don't take a free channel's last slots without asking.