Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

docs(bots): rewrite the bot guide as a short setup walkthrough (#9217)

Wolf Mermelsteinfacd2c648c29
diff --git a/crates/agent_code_mode/src/domain/documentation.json b/crates/agent_code_mode/src/domain/documentation.json
index 9b097b7d2a..81828eec3c 100644
--- a/crates/agent_code_mode/src/domain/documentation.json
+++ b/crates/agent_code_mode/src/domain/documentation.json
@@ -1086,7 +1086,7 @@
"ChannelPicture": "# Class: ChannelPicture\n\nAn uploaded channel profile picture in static file storage.\n\n## Properties\n\n| Property | Modifier | Type |\n| ------ | ------ | ------ |\n| <a id=\"property-id\"></a> `id` | `readonly` | `string` |",
"ChannelPicture.toJSON": "### toJSON()\n\n> **toJSON**(): \\{ `id`: `string`; \\}\n\nSerialize the uploaded picture reference.\n\n#### Returns\n\n\\{ `id`: `string`; \\}\n\n| Name | Type |\n| ------ | ------ |\n| `id` | `string` |",
"ChannelPicture.byId": "### byId()\n\n> `static` **byId**(`id`): `ChannelPicture`\n\nConstruct a reference from the upload receipt.\n\n#### Parameters\n\n| Parameter | Type |\n| ------ | ------ |\n| `id` | `string` |\n\n#### Returns\n\n`ChannelPicture`",
- "postToChannel": "# Function: postToChannel()\n\n> **postToChannel**(`client`, `target`, `body`, `images?`): `Promise`\\<`string`\\>\n\nPost a message using the endpoint supported by the caller's credentials.\n\nMost credentials use `POST /messages/channel/{id}`. User-owned bots without\nan acting user instead use `POST /channels/{id}/webhook`, which authorizes\nthrough channel membership. The bot owner is read from `GET /bots/me` and\ncached by the client.\n\nThe webhook endpoint supports content only. Mentions in `<m-*>` tags still\nwork, but threads and images are not supported.\n\nPosting to a `Thread` puts the message in that thread; to a `Channel`, at the\nchannel root. One target rather than a channel plus a thread id, so the two\ncan't disagree.\n\n## Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | `undefined` |\n| `target` | `Channel` \\| `Thread` | `undefined` |\n| `body` | `RichMessage` | `undefined` |\n| `images?` | `StaticImage`[] | `[]` |\n\n## Returns\n\n`Promise`\\<`string`\\>",
+ "postToChannel": "# Function: postToChannel()\n\n> **postToChannel**(`client`, `target`, `body`, `images?`): `Promise`\\<`string`\\>\n\nPost a message using the endpoint supported by the caller's credentials.\n\nMost credentials use `POST /messages/channel/{id}`. User-owned bots without\nan acting user instead use `POST /channels/{id}/webhook`, which authorizes\nthrough channel membership. The bot owner is read from `GET /bots/me` and\ncached by the client.\n\nThe webhook endpoint takes content only: the `mentions` list, threads and\nimages are dropped. `<m-*>` mention tags in the content still render and\nnotify, because the server extracts a bot's mentions from its content. A\nuser-owned bot gets the full API by acting as its owner with `requestedAs`.\n\nPosting to a `Thread` puts the message in that thread; to a `Channel`, at the\nchannel root. One target rather than a channel plus a thread id, so the two\ncan't disagree.\n\n## Parameters\n\n| Parameter | Type | Default value |\n| ------ | ------ | ------ |\n| `client` | `MacroClient` | `undefined` |\n| `target` | `Channel` \\| `Thread` | `undefined` |\n| `body` | `RichMessage` | `undefined` |\n| `images?` | `StaticImage`[] | `[]` |\n\n## Returns\n\n`Promise`\\<`string`\\>",
"Thread": "# Class: Thread\n\nA thread within a channel, rooted at a top-level message. Replies and\nthread-scoped posting live here.\n\n## Properties\n\n| Property | Modifier | Type | Description |\n| ------ | ------ | ------ | ------ |\n| <a id=\"property-channelid\"></a> `channelId` | `readonly` | `string` | - |\n| <a id=\"property-rootid\"></a> `rootId` | `readonly` | `string` | The id of the message this thread hangs off. |",
"Thread.channel": "### channel()\n\n> **channel**(): `Channel`\n\nThe channel this thread is in.\n\n#### Returns\n\n`Channel`",
"Thread.replies": "### replies()\n\n> **replies**(): `Promise`\\<`Message`[]\\>\n\nList the replies in this thread, oldest first.\n\n#### Returns\n\n`Promise`\\<`Message`[]\\>",
diff --git a/crates/bots/AGENTS.md b/crates/bots/AGENTS.md
index 5aa4c2d583..139b878ecb 100644
--- a/crates/bots/AGENTS.md
+++ b/crates/bots/AGENTS.md
@@ -49,3 +49,5 @@ for bot mutations that channel bots, agent triggers, and memory build on.
## Related
- Rules: `.agents/rules/rust/architecture.md`, `.agents/rules/observability.md`
+- Docs: [`docs/guides/bots.md`](../../docs/guides/bots.md) (setting up a bot
+ in the app and using it from the SDK)
diff --git a/docs/README.md b/docs/README.md
index 1b3a6e5151..8da2dd2e2a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,3 +16,6 @@ provider ([linked devices](architecture/whatsapp-linked-devices.md)) and the
[External view walkthrough](agent-guide/external.md).
Document sync: [DSS sync router](architecture/sync-router.md).
+
+Bots: [building a bot](guides/bots.md) (set one up in the app, then search and
+post from the TypeScript SDK).
diff --git a/docs/guides/README.md b/docs/guides/README.md
index c3d386a084..c327323e02 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -12,6 +12,7 @@ touches, in order, with the existing code to copy.
| A GraphQL field, query, mutation, or subscription | [add-graphql-field.md](add-graphql-field.md) |
| A notification kind | [add-notification-kind.md](add-notification-kind.md) |
| A Kafka topic, event, or consumer | [add-kafka-event.md](add-kafka-event.md) |
+| A bot that searches and posts to channels through the SDK | [bots.md](bots.md) |
| A MacroDB table, column, or query | [database guide](../development/database.md) |
| An AI tool | [`create-ai-tool` skill](../../.agents/skills/create-ai-tool/SKILL.md) |
| A backend endpoint to the TypeScript SDK | [`add-sdk-endpoint` skill](../../.agents/skills/add-sdk-endpoint/SKILL.md) |
diff --git a/docs/guides/bots.md b/docs/guides/bots.md
new file mode 100644
index 0000000000..95053aacd4
--- /dev/null
+++ b/docs/guides/bots.md
@@ -0,0 +1,85 @@
+# Building a bot
+
+A bot is a Macro account for a program, such as a release job or a webhook
+relay. It posts to channels under its own name. This guide creates one in the
+app, then uses it from TypeScript with
+[`@macro-inc/sdk`](https://sdk.macro.com).
+
+## 1. Create the bot
+
+Open **Settings → Developer → Bots** and click **Create bot**.
+
+![The Bots settings page](images/bots/settings-bots.png)
+
+Give the bot a name, and under **Channels** pick the channels it may post to.
+Only private and team channels are listed. You can change them later from the
+same page.
+
+![The Create a bot form with one channel selected](images/bots/create-bot.png)
+
+## 2. Copy the token
+
+Click **Create bot**, then copy the **Bot token**. It starts with `mbot_` and
+is shown only once, so put it in a secret store, not in code.
+
+![The Bot created page with the token masked](images/bots/bot-token.png)
+
+## 3. Send a message
+
+A bot you create is personal, so it posts as itself on your behalf:
+`requestedAs` names you, the owner, and the bot uses your access.
+
+```ts
+import { Macro } from '@macro-inc/sdk';
+
+const bot = new Macro({
+ auth: { type: 'bot', token: process.env.MACRO_BOT_TOKEN! },
+});
+const macro = bot.requestedAs(bot.users.byId('macro|[email protected]'));
+
+await macro.channels.byId('<channel-id>').send('Deploy finished');
+```
+
+The channel id is the last part of the channel's URL. The message is posted by
+the bot and shows who it was sent for:
+
+![The message from Release bot in #releases](images/bots/bot-message.png)
+
+## 4. Search
+
+Bots can't search: search rejects bot tokens. Search with an API key from
+**Settings → Developer → API Keys** instead. It acts as you.
+
+```ts
+import { Macro } from '@macro-inc/sdk';
+
+const macro = new Macro({ token: process.env.MACRO_API_KEY! });
+
+for await (const doc of macro.documents.search('roadmap', { pageSize: 5 })) {
+ console.log(doc.id, await doc.name());
+}
+```
+
+## What a bot can do
+
+- **Personal bot** (the default): owned by you. It acts only as you, through
+ `requestedAs`, and can read and post wherever you can.
+- **Team bot**: turn on **Advanced → Mentionable** when creating it. Only team
+ admins and owners can. Teammates can @mention it, and it can act as any
+ team member.
+- Messages are always credited to the bot, never to the user it acts for.
+- No bot can search, whoever owns it.
+
+## More
+
+- [SDK documentation](https://sdk.macro.com): authentication, threads,
+ mentions, edits and every other entity.
+- [Bots settings walkthrough](../agent-guide/settings.md#bots) for driving the
+ page in a browser.
+- Example bots:
+ [`anthropic-status-bot`](../../services/bots/anthropic-status-bot/README.md)
+ (posts through the channel webhook without acting as anyone) and
+ [`goalert-bot`](../../services/bots/goalert-bot/README.md) (threads, edits,
+ acting as a user).
+- Server code: [`crates/bots`](../../crates/bots/AGENTS.md). Who a bot may act
+ as is decided in `crates/macro_authorization/src/domain/bot_authorizer.rs`.
diff --git a/docs/guides/images/bots/bot-message.png b/docs/guides/images/bots/bot-message.png
new file mode 100644
index 0000000000..208a8f2057
Binary files /dev/null and b/docs/guides/images/bots/bot-message.png differ
diff --git a/docs/guides/images/bots/bot-token.png b/docs/guides/images/bots/bot-token.png
new file mode 100644
index 0000000000..29e6ae8c1c
Binary files /dev/null and b/docs/guides/images/bots/bot-token.png differ
diff --git a/docs/guides/images/bots/create-bot.png b/docs/guides/images/bots/create-bot.png
new file mode 100644
index 0000000000..b985a836b2
Binary files /dev/null and b/docs/guides/images/bots/create-bot.png differ
diff --git a/docs/guides/images/bots/settings-bots.png b/docs/guides/images/bots/settings-bots.png
new file mode 100644
index 0000000000..9bb7373acd
Binary files /dev/null and b/docs/guides/images/bots/settings-bots.png differ
diff --git a/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.md b/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.md
index 91cf280229..f213b0f813 100644
--- a/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.md
+++ b/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.md
@@ -9,8 +9,10 @@ an acting user instead use `POST /channels/{id}/webhook`, which authorizes
through channel membership. The bot owner is read from `GET /bots/me` and
cached by the client.
-The webhook endpoint supports content only. Mentions in `<m-*>` tags still
-work, but threads and images are not supported.
+The webhook endpoint takes content only: the `mentions` list, threads and
+images are dropped. `<m-*>` mention tags in the content still render and
+notify, because the server extracts a bot's mentions from its content. A
+user-owned bot gets the full API by acting as its owner with `requestedAs`.
Posting to a `Thread` puts the message in that thread; to a `Channel`, at the
channel root. One target rather than a channel plus a thread id, so the two
diff --git a/packages/sdk/src/entities/channels/post.ts b/packages/sdk/src/entities/channels/post.ts
index 5aa708d8de..c3dff8d848 100644
--- a/packages/sdk/src/entities/channels/post.ts
+++ b/packages/sdk/src/entities/channels/post.ts
@@ -13,8 +13,10 @@ import type { Thread } from './thread';
* through channel membership. The bot owner is read from `GET /bots/me` and
* cached by the client.
*
- * The webhook endpoint supports content only. Mentions in `<m-*>` tags still
- * work, but threads and images are not supported.
+ * The webhook endpoint takes content only: the `mentions` list, threads and
+ * images are dropped. `<m-*>` mention tags in the content still render and
+ * notify, because the server extracts a bot's mentions from its content. A
+ * user-owned bot gets the full API by acting as its owner with `requestedAs`.
*
* Posting to a `Thread` puts the message in that thread; to a `Channel`, at the
* channel root. One target rather than a channel plus a thread id, so the two