# Grok Bot

Connect [Grok Bot](https://docs.x.ai/grok-bot/overview) to [Roam HQ](https://ro.am)
chat. People message it in Roam, and it replies there.

Set it up in the Grok Bot app. After that, you talk to it in Roam.

## What you need

- The [Grok Bot](https://docs.x.ai/grok-bot/get-started) app
- A Roam HQ workspace

## Personal or organization

Choose one before you connect.

| | **Personal** | **Organization** |
| - | ------------ | ---------------- |
| **Appears in Roam as** | Your personal bot (name and icon on the token) | A named bot you configure (display name and avatar) |
| **Who can message it** | Only you | Anyone in the workspace who can reach it |
| **What it can see** | The direct message with that bot — not your DMs with other people, and not groups | Direct messages to the bot, plus groups you add it to |
| **Credential** | Personal Access Token (`rmp-…`) | API key (`rmk-…`) |
| **Use when** | A private assistant in Roam | A shared teammate others can @-mention |

Every bot on a Grok Bot account shares one computer (files, browser, logins).
If an organization key must stay isolated, use a dedicated Grok / Cursor
account for that bot.

## Connect

In Grok Bot, send:

```
Install this Roam plugin https://github.com/WonderInventions/grokbot-roam then connect Roam
```

Confirm the plugin. Grok Bot will ask for:

1. **A Roam credential** — create one below, then paste it when Grok Bot
   prompts you. Do not paste it into the chat.
2. **A routine URL and sender key** — Grok Bot creates a
   [routine](https://docs.x.ai/grok-bot/skills-routines-and-automations)
   (an automation Roam triggers on each new message). If it cannot read those
   values, copy them from the routine's details panel. Treat the sender key as
   a secret.

Grok Bot also adds Roam as an MCP server with **that same credential** (not a
second login). That is how it searches meetings and adds emoji reactions.

When that finishes, test in **Roam**, not only in the Grok Bot app.

## Personal

1. In Roam: **User Settings → Developer → Create Personal Access Token**
2. Name it (for example `grok-bot`)
3. Grant **Chat Send**, **Chat Read**, and **Meetings Read** (Chat Send
   includes images, files, and reactions)
4. Copy the token (`rmp-…`). Admins can require approval (the default) or
   disable personal tokens. If approval is required, an admin approves it
   under **Administration → Developer → Personal Access Tokens**. See
   [Access Models](/docs/guides/access-models#admin-policy-for-personal-access).

Give that token to Grok Bot when it asks.

Then in Roam, open a direct message with the personal bot and send:

> ping — reply with pong

You should see the reply in that Roam DM.

A personal bot cannot be added to groups. If you later want it to answer
@-mentions in groups you are in, ask Grok Bot after it is connected — that is
off by default.

## Organization

You need workspace-admin access in Roam.

1. **Roam Administration → Developer → Add ApiClient**
2. Choose **API Key**
3. Set the display name and avatar — that is what people see in Roam
4. Scopes, at minimum: `chat:send_message`, `chat:read`, `chat:history`,
   `group:read`, `webhook:write`, `item:write` (images and files),
   `meetings:read`
5. Copy the key (`rmk-…`)

Give that key to Grok Bot when it asks.

Then add the bot to each group it should read: **Group Settings** → add the
bot. @-mentioning it does not join the group. It can post to some public
groups without joining; it cannot read history there until it is a member.

In Roam, @-mention it in a group it belongs to, or send it a direct message:

> What is this channel for?

## If something goes wrong

| What you see | What to try |
| ------------ | ----------- |
| Nothing happens in Roam | In Grok Bot, reconnect Roam and paste **both** the routine URL and the sender key from the routine panel. |
| Connect rejects the URL | Use the URL from Grok Bot’s **routine** panel (it contains `/automations/webhook/`). |
| Org bot silent in a channel | Add it under that group’s **Group Settings**. |
| Personal bot answering other people | You likely used an API key. Recreate with a Personal Access Token. |
| It replies to every message in a busy group | Ask Grok Bot to listen only when @-mentioned. |
| It replies to itself in a loop | Ask Grok Bot to reconnect Roam so it reloads who it is. |
| It can see your DMs with other people | Reconnect. Personal setup should only attach the DM with the bot. |
| Images or files do not send or open | Personal: **Chat Send**. Org: the key needs `item:write`. Then reconnect. |
| Meeting or transcript questions fail | Personal: **Meetings Read**. Org: `meetings:read`. Reconnect and let Grok Bot add Roam MCP with the same token. |
| Cannot add an emoji reaction | Personal: **Chat Send**. Org: `chat:send_message`. Ask Grok Bot to use the roam MCP server — not a chat message. |

## Optional: call Roam tools from Grok

Connecting Roam chat already adds the roam MCP server on this Grok Bot. You
can also add it where you talk to Grok outside Roam — on
[grok.com](https://grok.com) or in
[Grok Build](https://docs.x.ai/build/features/mcp-servers).

| Where you talk to Grok | How to add Roam |
| ---------------------- | --------------- |
| Grok Bot | *Add a custom MCP server called roam at https://api.ro.am/mcp* (say **custom server**) |
| grok.com | [Connectors](https://grok.com/connectors) → New Connector → Custom |
| Grok Build | `grok mcp add --transport http roam https://api.ro.am/mcp` |

Personal access uses the OAuth prompt (or a PAT in the Authorization header).
Organization access uses an API key in that header. See
[MCP (AI Assistants)](/docs/integrations/mcp#grok).

## Grok as the model on Hermes or OpenClaw

To run Grok as the model inside [Hermes](/docs/integrations/hermes) or
[OpenClaw](/docs/integrations/openclaw) instead of Grok Bot, follow those
guides after pointing the agent at xAI.

## See also

- [Access Models](/docs/guides/access-models) — personal vs organization tokens
- [MCP (AI Assistants)](/docs/integrations/mcp) — tools Grok can call on Roam