Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
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.jsonindex 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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**.++++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.++++## 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.++++## 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:++++## 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.pngnew file mode 100644index 0000000000..208a8f2057Binary files /dev/null and b/docs/guides/images/bots/bot-message.png differdiff --git a/docs/guides/images/bots/bot-token.png b/docs/guides/images/bots/bot-token.pngnew file mode 100644index 0000000000..29e6ae8c1cBinary files /dev/null and b/docs/guides/images/bots/bot-token.png differdiff --git a/docs/guides/images/bots/create-bot.png b/docs/guides/images/bots/create-bot.pngnew file mode 100644index 0000000000..b985a836b2Binary files /dev/null and b/docs/guides/images/bots/create-bot.png differdiff --git a/docs/guides/images/bots/settings-bots.png b/docs/guides/images/bots/settings-bots.pngnew file mode 100644index 0000000000..9bb7373acdBinary files /dev/null and b/docs/guides/images/bots/settings-bots.png differdiff --git a/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.md b/packages/sdk-docs/reference/src/entities/channels/post/functions/postToChannel.mdindex 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 authorizesthrough channel membership. The bot owner is read from `GET /bots/me` andcached 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 thechannel root. One target rather than a channel plus a thread id, so the twodiff --git a/packages/sdk/src/entities/channels/post.ts b/packages/sdk/src/entities/channels/post.tsindex 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