Skip to main content

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-…).
export ROAM_TOKEN='rmk-…'

2. Find a group​

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

Copy a group id (plain UUID).

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

3. Post a markdown message​

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​

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.

Next steps​

  • GitHub Actions — drop-in workflow notifications
  • 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

If you need the bot to read messages and reply, use the Interactive bot quickstart instead.