Bot Documentation

Quick Start

Create a bot in User Settings, copy the Client ID and one-time Client Secret, then share the bot's install URL with a guild owner.

/oauth/bots/authorize?client_id=YOUR_CLIENT_ID&permissions=READ_MESSAGES,SEND_MESSAGES,USE_SLASH_COMMANDS

Authentication

Bot runtime requests authenticate with the Client ID and Client Secret. The Client ID stays stable; roll the secret if it leaks.

x-bot-client-id: YOUR_CLIENT_ID
x-bot-client-secret: YOUR_CLIENT_SECRET

x-bot-client-id: YOUR_CLIENT_ID
authorization: Bearer YOUR_CLIENT_SECRET

Error Responses

Bot API errors include a stable code field so integrations and future SDKs can branch on machine-readable failures.

{
  "error": "Bot does not have SEND_MESSAGES permission in this guild.",
  "code": "BOT_PERMISSION_MISSING",
  "details": { "permission": "SEND_MESSAGES" }
}

Permissions

Guild owners approve permissions when they install a bot. Bot developers can request permissions with an install URL, but installed guild permissions are controlled by that guild owner.

Runtime API

Use runtime endpoints from your bot service after the bot is installed in a guild.

{
  "content": "Hello from my bot"
}

{
  "name": "announcements",
  "type": "text"
}

{
  "name": "team-chat",
  "voiceBitrate": 64000,
  "voiceVideoQuality": "720p",
  "voiceUserLimit": 10
}

JavaScript SDK

The JavaScript SDK wraps bot credentials, slash command registration, webhook verification, and interaction responses so bot developers do not need to hand-roll REST calls.

Create a .env file beside your bot. The SDK loads it automatically, uses https://tactichat.com by default, creates or reuses the webhook at /webhooks/tactichat, and stores the webhook signing secret locally in .tactichat-bot.json.

TACTICHAT_BOT_CLIENT_ID=your-client-id
TACTICHAT_BOT_CLIENT_SECRET=your-client-secret
TACTICHAT_BOT_PUBLIC_URL=https://your-public-bot-url.example.com

const { TactiChatBot } = require("@tactichat/bot-sdk");

const bot = new TactiChatBot();

bot.command("help", async (interaction) => {
  const mentionedUser = interaction.firstMention();
  const target = mentionedUser
    ? bot.mentionUser(mentionedUser)
    : String(interaction.option("user", interaction.argumentText) || "").trim();

  await interaction.reply(
    target
      ? "Hi, " + target + ", this is the help message"
      : "Hi this is the help message"
  );
}, {
  description: "Show the help message",
  options: [
    {
      name: "user",
      description: "Optional user mention or name",
      type: "string",
      required: false
    }
  ]
});

bot.start();

Useful SDK Methods

• bot.start() registers commands, creates or reuses the webhook, and starts the listener.
• bot.command(name, handler, definition) defines a slash command handler.
• interaction.reply(content) responds to a slash command.
• interaction.firstMention() returns the first mentioned user object.
• bot.mentionUser(user) formats a user mention like @Trent.
• bot.mentionUsers(users) formats multiple user mentions.
• bot.listGuilds(), bot.listChannels(guildId), and bot.listMembers(guildId) fetch installed guild data.
• bot.deleteMessage(messageId) deletes a guild text-channel message.
• bot.createChannel(), bot.updateChannel(), and bot.deleteChannel() manage guild channels.
• bot.getConfigSummary() prints a safe diagnostic summary without revealing the client secret.

Use TACTICHAT_API_BASE_URL only for local or staging TactiChat servers. Use TACTICHAT_BOT_PUBLIC_WEBHOOK_URL only when you need to override the default webhook path.

Webhooks

Webhook subscriptions receive events for guilds where the bot is installed. Creating a webhook returns a one-time signing secret.

Webhook URLs must use public http or https hosts. Localhost, private networks, link-local addresses, and unresolved hosts are rejected by TactiChat. The SDK handles webhook signing secret storage automatically for SDK-created webhooks.

{
  "url": "https://example.com/tactichat/events",
  "events": ["MESSAGE_CREATE", "MESSAGE_UPDATE", "MESSAGE_DELETE", "SLASH_COMMAND"],
  "guildId": "optional-guild-id"
}

Supported Events

• MESSAGE_CREATE
• MESSAGE_UPDATE
• MESSAGE_DELETE
• SLASH_COMMAND
• GUILD_BOT_ADDED
• GUILD_BOT_REMOVED
• GUILD_BOT_PERMISSIONS_UPDATED

Transient failures are retried once. Webhooks are automatically disabled after repeated failed delivery attempts, 10 by default, and can be re-enabled by the bot owner.

GET /bot-api/webhooks/:webhookId/deliveries
POST /bot-api/webhooks/:webhookId/enable

Verify Signatures

Compute an HMAC SHA-256 signature over timestamp.body using the webhook signing secret, then compare it to x-tactichat-signature.

const crypto = require("crypto");

function verifySignature({ body, timestamp, signature, secret }) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Slash Commands

Bots can register global or guild-scoped command definitions. Users invoke them by typing /command in a text channel.

Slash command interactions include parsed mentions.users when users are mentioned in the argument text. Bot messages can mention one or more users by sending normal @username text.

{
  "name": "ping",
  "description": "Check if the bot is online",
  "options": [
    {
      "name": "target",
      "description": "Optional user or thing to ping",
      "type": "string",
      "required": false
    }
  ]
}

Interaction Payload

Subscribed webhooks receive an interaction id, raw argument text, parsed option values, and an expiresAt timestamp. Interactions must be answered before they expire, 15 minutes by default.

{
  "type": "SLASH_COMMAND",
  "data": {
    "interaction": {
      "id": "interaction-id",
      "commandName": "ping",
      "argumentText": "target",
      "options": { "target": "target" },
      "mentions": {
        "users": [
          { "id": "user-id", "username": "Trent", "avatar": null }
        ]
      },
      "expiresAt": "2026-06-09T12:15:00.000Z"
    }
  }
}

{
  "content": "Pong!"
}

Client Support

Web, desktop, and mobile text channels support slash command invocation through the normal message endpoint. The web and desktop apps include the full bot management UI in User Settings. Mobile shows bot lists and documentation access, with deeper bot creation and credential management planned as a native follow-up.

Platform Limits

• Accounts can own up to 25 bots by default.
• Guilds can install up to 50 bots by default.
• Each bot can register up to 25 webhooks and 100 slash commands by default.
• Bot runtime API requests are rate limited separately from normal user traffic.
• Bot security events and webhook delivery logs are retained for 7 days by default.

Endpoint Reference