bot setup

overview#

overlord supports creating tasks via chat bots. users can @bot develop "fix the login bug" in a group chat, and overlord dispatches the task automatically. notifications are sent back through the same channel.

lark setup#

1. create a lark app#

on lark open platform → custom app:

• note the app id and app secret
• event subscriptions: im.message.receive_v1, card.action.trigger
• request url: https://your-overlord-server.com/webhook/lark
• enable bot capability
• permissions: im:message, im:message:send_as_bot

2. register in overlord#

via admin → bot management → add bot, or via the api:

curl -X POST https://your-server:9000/api/admin/bots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "lark",
    "appId": "cli_xxx",
    "appSecret": "your-app-secret",
    "webhookToken": "your-verification-token",
    "name": "Overlord Bot"
  }'

3. bind chat groups to projects#

each chat group is bound to a default project so users don't need to specify --project every time:

curl -X POST https://your-server:9000/api/admin/bots/:botId/bindings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platformChatId": "oc_xxx",
    "projectKey": "PROJ",
    "chatName": "Project Dev Group"
  }'

4. link developer accounts#

each developer's lark open id must be linked to their overlord account via the platform_uid field. this mapping allows overlord to identify who is issuing bot commands.

update via admin → developers → edit, setting the platform uid to their lark open id.

slack setup#

1. create a slack app#

go to slack api → create new app → from scratch.

• note the app id and signing secret from basic information

2. configure bot token scopes#

under oauth & permissions, add these bot token scopes:

• chat:write — send messages
• chat:write.public — send messages to channels the bot isn't a member of
• app_mentions:read — receive @bot mentions
• im:read — read direct messages
• im:write — send direct messages
• users:read — look up user info

install the app to your workspace and copy the bot user oauth token (xoxb-...).

3. configure event subscriptions#

under event subscriptions:

• enable events
• set request url: https://your-overlord-server.com/webhook/slack/events
• subscribe to bot events: app_mention, message.im

4. enable interactivity#

under interactivity & shortcuts:

• toggle on
• set request url: https://your-overlord-server.com/webhook/slack/interact

5. add a slash command (optional)#

under slash commands → create new command:

• command: /overlord
• request url: https://your-overlord-server.com/webhook/slack/commands
• short description: run overlord bot commands

6. register in overlord#

curl -X POST https://your-server:9000/api/admin/bots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "slack",
    "appId": "A0XXXXXXX",
    "appSecret": "xoxb-your-bot-token",
    "webhookToken": "your-signing-secret",
    "name": "Overlord Bot"
  }'

note: appSecret = bot user oauth token, webhookToken = signing secret.

7. bind channels to projects#

same as lark, but use the slack channel id (C0XXXXXXX) as platformChatId:

curl -X POST https://your-server:9000/api/admin/bots/:botId/bindings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platformChatId": "C0XXXXXXX",
    "projectKey": "PROJ",
    "chatName": "#project-dev"
  }'

8. link developer accounts#

same as lark, but use the slack user id as platform_uid. find it via the user's profile → more → copy member id.

bot commands#

interactive cards#

when a pipeline reaches a confirmation stage, the bot sends an interactive card with action buttons (confirm / cancel / choice). users can respond directly from the chat interface without opening the web dashboard.

multi-bot architecture#

overlord supports multiple bot instances. each project or group can have its own bot on any supported platform. all bots share the same overlord backend. the server identifies which bot to use based on the app_id in the incoming request.

next steps#

• developer setup — install the developer cli
• deployment guide — deploy with cloudflare zero trust
• bot integration guide — interactive cards, troubleshooting, adapter pattern