chattocorp · hmans · Aug 11, 2026
diff --git a/apps/docs-website/astro.config.mjs b/apps/docs-website/astro.config.mjs
@@ -99,6 +99,7 @@ export default defineConfig({
           label: "Integrations",
           items: [
             "guides/integrations/chatto-api",
+            "guides/integrations/bots",
             "guides/integrations/api-compatibility",
             "guides/integrations/external-login-providers",
             "guides/integrations/community-shields",
@@ -132,6 +133,7 @@ export default defineConfig({
                 "reference/connectrpc-api/assets",
                 "reference/connectrpc-api/asset-uploads",
                 "reference/connectrpc-api/bots",
+                "reference/connectrpc-api/bot-runtime",
                 "reference/connectrpc-api/messages",
                 "reference/connectrpc-api/message-search",
                 "reference/connectrpc-api/account",

diff --git a/apps/docs-website/src/content/docs/guides/integrations/bots.mdx b/apps/docs-website/src/content/docs/guides/integrations/bots.mdx
@@ -0,0 +1,62 @@
+---
+title: Bot Accounts and Capabilities
+description: Create an accountable bot, approve narrow capabilities, and use the bot-only direct-message API.
+---
+
+import { Aside, CardGrid, LinkCard } from "@astrojs/starlight/components";
+
+Bot accounts are visible automation identities owned by one human account. A
+bot's profile shows its purpose, data-handling description, and the application
+capabilities its owner or a server administrator approved.
+
+<Aside type="caution">
+  Bot APIs are experimental in Chatto 0.5. Pin and test the server versions your integration supports, and treat capability identifiers as unstable until Chatto reaches 1.0.
+</Aside>
+
+## The Authorization Model
+
+A capability is an upper bound, not blanket access. Chatto allows a bot
+operation only when all three conditions hold:
+
+1. the server granted the bot the required application capability;
+2. the bot's human owner still has the corresponding authority; and
+3. the bot has an explicit relationship with the target conversation.
+
+Removing a grant or reducing the owner's authority takes effect immediately.
+Bots do not receive roles or direct RBAC permissions and cannot enumerate or
+self-join rooms.
+
+## Initial Capabilities
+
+| Capability | Allows |
+| ---------- | ------ |
+| `dm.messages.read` | Listing and reading complete histories of DMs in which the bot is an explicit participant. Users cannot start a DM with the bot without this grant. |
+| `messages.write` | Posting text messages through the bot runtime API, currently only in DMs in which the bot is an explicit participant. |
+
+Use `BotService.ListApplicationCapabilities` instead of hard-coding this table.
+The response is the exhaustive catalogue understood by that server and includes
+the same names and explanations shown on bot profiles.
+
+## Credentials and API Boundaries
+
+Bot creation issues one show-once API key. Send it as a bearer token only to
+`BotRuntimeService`. The normal user ConnectRPC API, realtime WebSocket,
+protected asset endpoints, room directory, and self-join operations reject bot
+keys even when the key itself is valid.
+
+The initial bot runtime API supports listing explicit bot DMs, reading their
+timeline pages, and posting text messages. Use the opaque timeline cursors
+unchanged and never derive storage coordinates from them.
+
+## Disclosure
+
+Write a concrete bot description that tells people what the integration does
+and how it handles conversation data. Chatto displays that description and the
+server-authored capability list on public profile cards, so users can make an
+informed choice before starting a DM.
+
+<CardGrid>
+  <LinkCard title="Bot Management API" href="/reference/connectrpc-api/bots/" description="Create bots, rotate keys, and approve capabilities." />
+  <LinkCard title="Bot Runtime API" href="/reference/connectrpc-api/bot-runtime/" description="Capability-gated operations for bot API keys." />
+  <LinkCard title="API Compatibility" href="/guides/integrations/api-compatibility/" description="Version-skew and experimental API guidance." />
+</CardGrid>
diff --git a/apps/docs-website/src/content/docs/guides/integrations/chatto-api.mdx b/apps/docs-website/src/content/docs/guides/integrations/chatto-api.mdx
@@ -34,7 +34,7 @@ Discovery is also the right place for custom clients to learn public server iden
 | ------------ | ---------- |
 | Same-origin browser app | HTTP-only cookie session, with bearer token support in the bundled client. |
 | Cross-origin Chatto frontend | OAuth authorization code with PKCE, then opaque bearer token. |
-| Bot or service integration | Opaque bearer token from an authorized flow. |
+| Bot integration | Show-once bot API key, accepted only by capability-aware bot services. |
 | Local recovery automation | Operator socket, not user auth. |
 
 Bearer tokens are opaque runtime credentials stored server-side. They are not JWTs.
@@ -64,6 +64,7 @@ Realtime delivery uses the same room membership, RBAC, projection readiness, and
 | Read users and profiles | `UserService.ListUsers`, `GetUser`, and `BatchGetUsers` |
 | Manage roles or permissions | `chatto.admin.v1` role and permission services |
 | Inspect operational health | `AdminDiagnosticsService`, metrics, and exporter |
+| Run a bot integration | `BotService` for management and `BotRuntimeService` for approved operations |
 
 ## Message Body Tokens
 
@@ -94,5 +95,6 @@ support inline timestamps.
   <LinkCard title="Realtime API" href="/reference/connectrpc-api/realtime/" description="Protobuf realtime WebSocket frame reference." />
   <LinkCard title="Server Discovery" href="/reference/connectrpc-api/server-discovery/" description="Discovery endpoint for compatible clients." />
   <LinkCard title="API Compatibility" href="/guides/integrations/api-compatibility/" description="Experimental API posture and version-skew guidance." />
+  <LinkCard title="Bot Accounts" href="/guides/integrations/bots/" description="Capability-gated automation identities and runtime API." />
   <LinkCard title="Operator CLI" href="/guides/operations/operator-cli/" description="Trusted local automation over the operator socket." />
 </CardGrid>
diff --git a/apps/docs-website/src/content/docs/reference/connectrpc-api/bot-runtime.mdx b/apps/docs-website/src/content/docs/reference/connectrpc-api/bot-runtime.mdx
@@ -0,0 +1,122 @@
+---
+title: BotRuntimeService
+description: Capability-gated direct-message RPCs for bot credentials.
+editUrl: false
+---
+
+{/* Generated from proto/chatto/{auth,discovery,api,admin,realtime}/v1/*.proto. Do not edit directly. */}
+
+Chatto exposes this service below `/api/connect`.
+
+
+
+Shared message and enum definitions are documented in [Shared Types And Enums](/reference/connectrpc-api/types/).
+
+
+
+<a id="chatto-api-v1-BotRuntimeService"></a>
+
+## BotRuntimeService
+
+Narrow runtime API available only to bot API-key credentials.
+
+<a id="chatto-api-v1-BotRuntimeService-ListBotDirectMessages"></a>
+
+### ListBotDirectMessages
+
+No method description provided.
+
+```http
+POST /api/connect/chatto.api.v1.BotRuntimeService/ListBotDirectMessages
+```
+
+<a id="chatto-api-v1-ListBotDirectMessagesRequest"></a>
+
+#### Input: ListBotDirectMessagesRequest
+
+Request the direct-message conversations explicitly shared with the bot.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `page` | [`PageRequest`](/reference/connectrpc-api/types/#chatto-api-v1-PageRequest) | No field description provided. |
+
+
+<a id="chatto-api-v1-ListBotDirectMessagesResponse"></a>
+
+#### Result: ListBotDirectMessagesResponse
+
+Direct-message conversations visible to the authenticated bot.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `rooms` | repeated [`Room`](/reference/connectrpc-api/types/#chatto-api-v1-Room) | No field description provided. |
+| `page` | [`PageInfo`](/reference/connectrpc-api/types/#chatto-api-v1-PageInfo) | No field description provided. |
+
+
+<a id="chatto-api-v1-BotRuntimeService-GetBotDirectMessageEvents"></a>
+
+### GetBotDirectMessageEvents
+
+No method description provided.
+
+```http
+POST /api/connect/chatto.api.v1.BotRuntimeService/GetBotDirectMessageEvents
+```
+
+<a id="chatto-api-v1-GetBotDirectMessageEventsRequest"></a>
+
+#### Input: GetBotDirectMessageEventsRequest
+
+Request one page of a bot's direct-message conversation.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `room_id` | `string` | No field description provided. |
+| `limit` | `int32` | No field description provided. |
+| `cursor.before` | `string` | No field description provided. |
+| `cursor.after` | `string` | No field description provided. |
+
+
+<a id="chatto-api-v1-GetBotDirectMessageEventsResponse"></a>
+
+#### Result: GetBotDirectMessageEventsResponse
+
+One authorized direct-message timeline page.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `page` | [`RoomTimelinePage`](/reference/connectrpc-api/types/#chatto-api-v1-RoomTimelinePage) | No field description provided. |
+
+
+<a id="chatto-api-v1-BotRuntimeService-CreateBotDirectMessage"></a>
+
+### CreateBotDirectMessage
+
+No method description provided.
+
+```http
+POST /api/connect/chatto.api.v1.BotRuntimeService/CreateBotDirectMessage
+```
+
+<a id="chatto-api-v1-CreateBotDirectMessageRequest"></a>
+
+#### Input: CreateBotDirectMessageRequest
+
+Request a text message in a direct-message conversation shared with the bot.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `room_id` | `string` | No field description provided. |
+| `body` | `string` | No field description provided. |
+| `in_reply_to` | `string` | No field description provided. |
+
+
+<a id="chatto-api-v1-CreateBotDirectMessageResponse"></a>
+
+#### Result: CreateBotDirectMessageResponse
+
+The message created by the bot.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `message` | [`Message`](/reference/connectrpc-api/types/#chatto-api-v1-Message) | No field description provided. |
diff --git a/apps/docs-website/src/content/docs/reference/connectrpc-api/bots.mdx b/apps/docs-website/src/content/docs/reference/connectrpc-api/bots.mdx
@@ -21,6 +21,35 @@ Shared message and enum definitions are documented in [Shared Types And Enums](/
 Manages bot accounts owned by the authenticated human or, with
 administrative authority, by other users.
 
+<a id="chatto-api-v1-BotService-ListApplicationCapabilities"></a>
+
+### ListApplicationCapabilities
+
+Lists every application capability recognised by this server. The
+catalogue is shared vocabulary intended for bots and future OAuth apps.
+
+```http
+POST /api/connect/chatto.api.v1.BotService/ListApplicationCapabilities
+```
+
+<a id="chatto-api-v1-ListApplicationCapabilitiesRequest"></a>
+
+#### Input: ListApplicationCapabilitiesRequest
+
+Request the application capabilities recognised by this server.
+
+
+<a id="chatto-api-v1-ListApplicationCapabilitiesResponse"></a>
+
+#### Result: ListApplicationCapabilitiesResponse
+
+Exhaustive server capability catalogue.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `capabilities` | repeated [`ApplicationCapability`](/reference/connectrpc-api/types/#chatto-api-v1-ApplicationCapability) | No field description provided. |
+
+
 <a id="chatto-api-v1-BotService-ListBots"></a>
 
 ### ListBots
@@ -294,3 +323,37 @@ Bot API-key revocation response.
 | Field | Type | Description |
 | --- | --- | --- |
 | `bot` | [`Bot`](/reference/connectrpc-api/types/#chatto-api-v1-Bot) | Bot with absent API-key metadata after successful revocation. |
+
+
+<a id="chatto-api-v1-BotService-SetBotCapabilities"></a>
+
+### SetBotCapabilities
+
+Replaces the approved capabilities for one manageable bot. Unknown
+identifiers are rejected and removal takes effect immediately.
+
+```http
+POST /api/connect/chatto.api.v1.BotService/SetBotCapabilities
+```
+
+<a id="chatto-api-v1-SetBotCapabilitiesRequest"></a>
+
+#### Input: SetBotCapabilitiesRequest
+
+Replace one manageable bot's approved application capabilities.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `bot_id` | `string` | No field description provided. |
+| `capability_ids` | `repeated string` | No field description provided. |
+
+
+<a id="chatto-api-v1-SetBotCapabilitiesResponse"></a>
+
+#### Result: SetBotCapabilitiesResponse
+
+Updated bot after replacing its approved capabilities.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `bot` | [`Bot`](/reference/connectrpc-api/types/#chatto-api-v1-Bot) | No field description provided. |
diff --git a/apps/docs-website/src/content/docs/reference/connectrpc-api/index.mdx b/apps/docs-website/src/content/docs/reference/connectrpc-api/index.mdx
@@ -219,6 +219,7 @@ Use the service pages below for request and response fields. Shared messages and
 ### chatto.api.v1
 
 - [BotService](/reference/connectrpc-api/bots/) - Bot account lifecycle and management RPCs.
+- [BotRuntimeService](/reference/connectrpc-api/bot-runtime/) - Capability-gated direct-message RPCs for bot credentials.
 - [AssetService](/reference/connectrpc-api/assets/) - Room-scoped asset metadata and signed URL read RPCs.
 - [AssetUploadService](/reference/connectrpc-api/asset-uploads/) - Chunked room-scoped attachment upload RPCs.
 - [MessageService](/reference/connectrpc-api/messages/) - Message creation, editing, deletion, composer link-preview, reaction, and attachment RPCs.