# Quickstart: Notification Bot

Post alerts from CI/CD, monitoring, or ticketing into a Roam group in under ten minutes.
Uses an **organization API key** — no OAuth or webhooks required.

## 1. Create an API key

1. Open **Roam Administration → Developer** (gear → Settings).
2. Click **Add ApiClient**, choose **API key**, name it (e.g. `ci-bot`).
3. Grant scopes: `group:read`, `chat:send_message` (or the UI label **Chat Send**).
4. Save and copy the API key (`rmk-…`).

```bash
export ROAM_TOKEN='rmk-…'
```

## 2. Find a group

```bash
curl -sS -H "Authorization: Bearer $ROAM_TOKEN" \
  https://api.ro.am/v1/group.list | jq .
```

Copy a group `id` (plain UUID).

```bash
export GROUP_ID='88bebce7-6cbb-4666-96f9-5c02d73e6661'
```

## 3. Post a markdown message

```bash
curl -sS -X POST https://api.ro.am/v1/chat.post \
  -H "Authorization: Bearer $ROAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"groupId\": \"$GROUP_ID\",
    \"text\": \"**Deploy succeeded** on \`main\` — build 42 is live.\"
  }" | jq .
```

A successful response includes `"ok": true` and the new message timestamps.

## 4. (Optional) Post Block Kit

```bash
curl -sS -X POST https://api.ro.am/v1/chat.post \
  -H "Authorization: Bearer $ROAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"groupId\": \"$GROUP_ID\",
    \"blocks\": [
      {
        \"type\": \"header\",
        \"text\": { \"type\": \"plain_text\", \"text\": \"Deploy succeeded\" }
      },
      {
        \"type\": \"section\",
        \"text\": {
          \"type\": \"mrkdwn\",
          \"text\": \"Service **api-gateway** is live.\\nVersion: \`v2.4.1\`\"
        }
      }
    ],
    \"color\": \"good\"
  }" | jq .
```

Supported blocks: [Block Kit guide](/docs/guides/block-kit).

## Next steps

- [GitHub Actions](/docs/integrations/github-actions) — drop-in workflow notifications
- [Webhook Relays](/docs/integrations/webhook-relays) — forward external webhooks into chat without code
- Threads: pass `threadKey` on `chat.post` to keep related alerts grouped
- Rate limits: burst 10 / 1 rps — see [API Reference](/docs/api/api#rate-limiting)

If you need the bot to **read** messages and reply, use the
[Interactive bot](/docs/guides/quickstart-interactive-bot) quickstart instead.