Core concepts

Bot and owner

A bot is an isolated identity with a display_name, a name_bot username, and its own credentials. Its owner manages it, but the bot never inherits the owner’s permissions.

Installation and session

A direct chat is created only after the user selects Add bot. Installation sends /start and creates a session_id. Restart clears history and issues a new session_id.

Access scope

In direct chats a bot sees only its session events. In groups it receives @mentions and replies to its own messages, never room history or the member list.

Transport

Webhook is the supported MVP transport. WebSocket is reserved for a future stable protocol.

SDK practice

An SDK grants no additional permissions: every call remains scoped by the platform to the authenticated bot and an allowed chat.

Create one client per bot token. If a process serves multiple bots, select credentials only after resolving the incoming bot_id.

import { KeyChatBot } from '@keychat/bots';

const bot = new KeyChatBot(process.env.KEYCHAT_BOT_TOKEN!);