Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

Create a command

name is the trigger without the ! prefix; the bot’s built-in triggers are reserved. Responses support the same template variables as the dashboard’s Chat bot page - {user}, {touser}, {args}, {arg:N}, {pick:a|b|c}, {random:1-100}, {list:name}, {if:...}, {repeat:N|...}, {uptime}, {ai:...} and more, and variables nest (full reference: https://docs.tippage.com/chat-bot/variables). Response lists themselves are managed in the dashboard. A streamer can have at most 250 commands. Requires commands:manage.

POST/commands
Authorization
AuthorizationBearer token (tp_live_... or tpat_...) · headerrequired

A TipPage API key (tp_live_..., created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (tpat_..., see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.

Request body
requiredapplication/json
namestringrequired

The trigger without the ! prefix - lowercase letters, numbers, hyphens, and underscores. The bot's built-in triggers are reserved.

max length 50 · matches ^[a-z0-9_-]+$
responsestringrequired

The template. Can't start with / or !. Its fixed wording (everything outside {variables}) must fit in one 500-character chat message; the rendered chat line is cut to 500.

max length 2500
descriptionstring | null

Viewer-facing blurb for the tip page's command list. Plain text.

max length 200
listedboolean
default: true
ai_memoryboolean
default: false
ai_memory_sharedboolean
default: false
platformsstring[]

Which chat(s) the command answers in. At least one.

default: ["twitch","kick"]
permissionstring
default: "everyone"
Allowed:everyonesubscribermoderator
cooldown_secondsinteger
min 0 · max 3600 · default: 0
cooldown_typestring
default: "global"
Allowed:globalper_user
aliasesstring[]

Same lexical rules as name; max 10.

max items 10
enabledboolean
default: true
Responses
201

Created. Active in chat within a few seconds.

commandCustomCommand
Show properties
namestring

The trigger, without the ! prefix.

responsestring

What the bot answers. Template variables supported.

descriptionstring | null

Optional viewer-facing blurb shown on the tip page's command list instead of the response. null = the page shows a preview of the response with variables rendered as labels ({urlfetch:} addresses and {ai:} prompts are never shown).

max length 200
listedboolean

Whether the command appears on the tip page's command list. It works in chat either way.

ai_memoryboolean

{ai:} conversation memory - when true the character remembers this command's last 15 exchanges (with timestamps, kept until the command is deleted) and reacts to repeats and returning viewers. Only meaningful for responses containing {ai:}. Memory is per platform unless ai_memory_shared.

ai_memory_sharedboolean

One memory for Twitch and Kick instead of one per platform. Only meaningful with ai_memory.

platformsstring[]

Which chat(s) it runs in. Default both. A platform the streamer hasn't connected is simply skipped; the set can't be empty (use enabled: false to bench it).

permissionstring

Who can trigger it. subscriber includes moderators; moderator includes the streamer.

Allowed:everyonesubscribermoderator
cooldown_secondsinteger
min 0 · max 3600
cooldown_typestring

global = one shared cooldown for the whole channel; per_user = each viewer gets their own.

Allowed:globalper_user
aliasesstring[]

Extra triggers for the same command, also without the !.

enabledboolean
created_atstring<date-time>
updated_atstring<date-time>
400

Invalid fields (invalid_command), or the streamer already has 250 commands (limit_reached).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

401

Missing or invalid credential (missing_api_key / invalid_api_key, or invalid_token for an expired/revoked OAuth access token).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

403

The key lacks the required scope (missing_scope).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

required_scopestring
409

Name already taken (command_exists), or an alias collides with another trigger (alias_in_use).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

429

Rate limit exceeded - check the RateLimit-* headers.

errorstring
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.tippage.com/v1/commands' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "response": "string",
  "description": "string",
  "listed": true,
  "ai_memory": false,
  "ai_memory_shared": false,
  "platforms": [
    "twitch",
    "kick"
  ],
  "permission": "everyone",
  "cooldown_seconds": 0,
  "cooldown_type": "global",
  "aliases": [
    "string"
  ],
  "enabled": true
}'
Response
{
  "command": {
    "name": "discord",
    "response": "string",
    "description": "string",
    "listed": true,
    "ai_memory": true,
    "ai_memory_shared": true,
    "platforms": [
      "twitch"
    ],
    "permission": "everyone",
    "cooldown_seconds": 0,
    "cooldown_type": "global",
    "aliases": [
      "string"
    ],
    "enabled": true,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}