Skip to main content

​
Overview

The Bots API allows you to create custom bots with specific permissions (scopes), manage bot lifecycle, regenerate API tokens, and provide a marketplace for installing public bots. Bots can respond to commands, send messages, and integrate with external services via webhooks.

​
Bot Scopes

Scopes define what permissions a bot has:
  • messages:read - Read messages in channels
  • messages:write - Send messages to channels
  • channels:read - Read channel information
  • channels:write - Create and modify channels
  • users:read - Read user information
  • reactions:write - Add reactions to messages
  • commands:register - Register slash commands

​
Bot Management

These methods are for bot creators to manage their bots.

​
bot.create

Create a new bot with specified scopes and permissions. Returns a plain API token that is only shown once.
​
name
string
required
Bot name (1-100 characters)
​
description
string
Bot description (max 500 characters)
​
webhookUrl
string
URL to receive bot events and command invocations
​
scopes
BotScope[]
required
Array of permission scopes for the bot
​
isPublic
boolean
default:false
Whether the bot is listed in the public marketplace
​
data
Bot
The created bot object
​
token
string
Plain API token - only returned on creation, store securely
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • UnauthorizedError - User is not authenticated
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
const result = await client.rpc("bot.create", {
  name: "GitHub Bot",
  description: "Sends GitHub notifications to channels",
  webhookUrl: "https://example.com/bot/webhook",
  scopes: ["messages:write", "channels:read"],
  isPublic: true
})

console.log("Bot created:", result.data.id)
console.log("API Token (save this!):", result.token)

​
bot.list

List all bots created by users in your organization.
​
data
Bot[]
Array of bots created in your organization
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Server error
const result = await client.rpc("bot.list", {})
console.log(`Found ${result.data.length} bots`)

​
bot.get

Get details for a specific bot by ID.
​
id
BotId
required
Bot identifier
​
data
Bot
Bot object
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not org admin or bot creator
  • InternalServerError - Server error
const result = await client.rpc("bot.get", {
  id: "bot_abc123"
})
console.log("Bot:", result.data.name)

​
bot.update

Update bot configuration including name, description, webhook URL, scopes, or visibility.
​
id
BotId
required
Bot identifier
​
name
string
New bot name (1-100 characters)
​
description
string | null
New description (max 500 characters), set to null to clear
​
webhookUrl
string | null
New webhook URL, set to null to clear
​
scopes
BotScope[]
New array of permission scopes
​
isPublic
boolean
Whether bot should be public in marketplace
​
data
Bot
Updated bot object
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not org admin or bot creator
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
const result = await client.rpc("bot.update", {
  id: "bot_abc123",
  name: "GitHub Bot v2",
  scopes: ["messages:write", "channels:read", "reactions:write"]
})

​
bot.delete

Soft delete a bot. The bot will be disabled and hidden but can potentially be restored.
​
id
BotId
required
Bot identifier
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not org admin or bot creator
  • InternalServerError - Server error
await client.rpc("bot.delete", {
  id: "bot_abc123"
})

​
bot.regenerateToken

Generate a new API token for a bot. The old token is invalidated immediately.
​
id
BotId
required
Bot identifier
​
data
Bot
Bot object with updated token hash
​
token
string
New plain API token - store securely
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not org admin or bot creator
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
const result = await client.rpc("bot.regenerateToken", {
  id: "bot_abc123"
})
console.log("New token (save this!):", result.token)

​
bot.updateAvatar

Update the bot’s avatar image URL.
​
id
BotId
required
Bot identifier
​
avatarUrl
string
required
URL to the bot’s avatar image
​
data
Bot
Updated bot object
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not bot creator
  • InternalServerError - Server error
await client.rpc("bot.updateAvatar", {
  id: "bot_abc123",
  avatarUrl: "https://example.com/avatars/bot.png"
})

​
bot.getCommands

List all commands registered by a bot.
​
botId
BotId
required
Bot identifier
​
data
BotCommand[]
Array of bot commands
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • UnauthorizedError - User is not org admin
  • InternalServerError - Server error
const result = await client.rpc("bot.getCommands", {
  botId: "bot_abc123"
})
console.log(`Bot has ${result.data.length} commands`)

​
Bot Marketplace

These methods are for users to discover and install public bots.

​
bot.listPublic

Browse all public bots available for installation. Returns bots with their installation status for your organization.
​
search
string
Optional search query to filter bots
​
data
PublicBotInfo[]
Array of public bots
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Server error
const result = await client.rpc("bot.listPublic", {
  search: "github"
})

for (const bot of result.data) {
  console.log(`${bot.name} by ${bot.creatorName}`)
  console.log(`Installed: ${bot.isInstalled}`)
}

​
bot.listInstalled

List all bots installed in your organization.
​
data
Bot[]
Array of installed bots
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Server error
const result = await client.rpc("bot.listInstalled", {})
console.log(`${result.data.length} bots installed`)

​
bot.install

Install a public bot to your organization.
​
botId
BotId
required
ID of the public bot to install
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist or is not public
  • BotAlreadyInstalledError - Bot is already installed
  • UnauthorizedError - User is not org admin
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
await client.rpc("bot.install", {
  botId: "bot_abc123"
})
console.log("Bot installed successfully")

​
bot.installById

Install a bot by ID, regardless of whether it’s public or private. This allows users to install bots by sharing their bot ID directly.
​
botId
BotId
required
ID of the bot to install
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot doesn’t exist
  • BotAlreadyInstalledError - Bot is already installed
  • UnauthorizedError - User is not org admin
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
await client.rpc("bot.installById", {
  botId: "bot_xyz789"
})

​
bot.uninstall

Remove a bot from your organization.
​
botId
BotId
required
ID of the bot to uninstall
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • BotNotFoundError - Bot is not installed
  • UnauthorizedError - User is not org admin
  • RateLimitExceededError - Too many requests
  • InternalServerError - Server error
await client.rpc("bot.uninstall", {
  botId: "bot_abc123"
})

Build docs developers (and LLMs) love

Get started for freeTalk to us