---
search:
  tags:
    - Chat bot
    - POST
seo:
  description: >-
    name is the trigger without the ! prefix; the bot's built-in triggers are
    reserved.… Reference for the POST /commands endpoint in the TipPage
    Developer API.
sidebar:
  label: Create a command
  badge: POST
title: Create a command
type: openapi-operation
---
`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`

**Request body** (`application/json`, required)

- `name` (string, required) — The trigger without the \`!\` prefix - lowercase letters, numbers, hyphens, and underscores. The bot's built-in triggers are reserved.
- `response` (string, required) — 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.
- `description` (string | null) — Viewer-facing blurb for the tip page's command list. Plain text.
- `listed` (boolean)
- `ai_memory` (boolean)
- `ai_memory_shared` (boolean)
- `platforms` (string[]) — Which chat(s) the command answers in. At least one.
- `permission` (string)
- `cooldown_seconds` (integer)
- `cooldown_type` (string)
- `aliases` (string[]) — Same lexical rules as \`name\`; max 10.
- `enabled` (boolean)

Request body example:

```json
{
  "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
}
```

**Responses**

- `201` — Created. Active in chat within a few seconds.
- `400` — Invalid fields (\`invalid\_command\`), or the streamer already has 250 commands (\`limit\_reached\`).
- `401` — Missing or invalid credential (\`missing\_api\_key\` / \`invalid\_api\_key\`, or \`invalid\_token\` for an expired/revoked OAuth access token).
- `403` — The key lacks the required scope (\`missing\_scope\`).
- `409` — Name already taken (\`command\_exists\`), or an alias collides with another trigger (\`alias\_in\_use\`).
- `429` — Rate limit exceeded - check the \`RateLimit-\*\` headers.

Response example, 201:

```json
{
  "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"
  }
}
```
