---
title: "Bot Commands"
description: "Run commands and send chat messages through the API."
canonical: "https://developers.fnlb.net/docs/bot-commands"
markdown: "/docs/bot-commands.md"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Bot Commands

Commands are how you change cosmetics, run emotes, and trigger bot behavior over HTTP. They use the same names as in-game bot commands, **without** a category prefix.

## Run a command

[POST /bots/{botId}/commands/run](/api?method=POST&path=/bots/{botId}/commands/run) accepts:

| Field | Required | Description |
| :--- | :--- | :--- |
| `command` | yes | Command name, 1–255 characters. |
| `args` | no | One string or an array of up to 25 strings. |
| `locale` | no | Reply language. See the route schema for allowed values. |

OAuth2 tokens need the `commands.run` scope. API tokens and sessions are accepted when the route lists them.

```bash
curl -X POST "https://api.fnlb.net/v1/bots/BOT_ID/commands/run" \
  -H "Authorization: Bearer FNLB_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"outfit","args":"Renegade Raider","locale":"en"}'
```

## Response

A successful call returns HTTP `200` with a **reply object**, not the updated party:

```json
{
  "nonce": "…",
  "botName": "Alpha",
  "content": "Set outfit to Renegade Raider.",
  "format": 1
}
```

| `format` | Meaning |
| :--- | :--- |
| `0` | Neutral |
| `1` | Success |
| `2` | Info |
| `3` | Warning |
| `4` | Error |

The bot can answer with `format: 4` while HTTP stays `200`. Treat `content` and `format` as the command outcome. Read party state from the [gateway](/gateway.md) if you need cosmetics on members.

## Chat messages

[POST /bots/{botId}/chat/messages](/api?method=POST&path=/bots/{botId}/chat/messages) sends text the bot delivers in party chat. It also requires `commands.run`. The body has `content` and optional `locale`. The same reply shape as command run is returned.

Use commands for bot actions. Use chat when you need a custom message string.

## Rate limit

This route allows about **250** requests per 10 minutes per IP with an API token, and **1000** with an OAuth2 access token. See [Rate limits](/docs/rate-limits.md#api).

## Related

- Bot ids come from [GET /bots](/api?method=GET&path=/bots). See [Bots and categories](/docs/bots-and-categories.md).
- [Presets](/docs/presets.md) store cosmetic setups you apply through commands, not a separate HTTP action.