# 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.

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** and **Chat Read** (Chat Send includes images and files)
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)
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. |

## Optional: call Roam tools from Grok

The steps above put Grok in Roam chat. You can also give Grok tools to search
meetings and messages while you talk to it in the Grok Bot app, 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