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.

3.5 KB
Raw Blame

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.

1. Create the bot

Open Settings → Developer → Bots and click Create bot.

The Bots settings page

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

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

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.

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

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.

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());
}

Manage bots from code

An API key can do everything the settings page does: create and configure bots, grant channels, read webhook URLs and mint or revoke tokens.

const macro = new Macro({ token: process.env.MACRO_API_KEY! });

const bot = await macro.bots.create({ name: 'Release bot', handle: 'release-bot' });
await bot.grantChannel(macro.channels.byId('<channel-id>'));
const { secret } = await bot.createToken({ label: 'ci' });
const [webhook] = await bot.webhooks();

secret is shown only once. POST { "content": "..." } to webhook.url with the token in x-macro-bot-token and x-macro-bot-scope: user.

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