Discord Bot Port

Purpose

This is the Harbor reference integration for the Discord Bot API.

Use it when:

• building Discord bot actions in Harbor
• extending the Dock / Hub Discord Bot API entry
• teaching Codex or OpenClaw how to map a bot chat API into Harbor Ports and Harbor Actions without turning Harbor into a generic messaging proxy

Harbor Port worksheet

Product

• Product: Discord Bot API
• Publisher slug: discord
• Publisher name: Discord
• Category: Messaging
• Tags: discord, bot, chat, guilds, messaging

Safe Harbor Port metadata

• Kind: http_api
• Label: Discord Bot API
• Description: Discord Bot API connection managed locally through Harbor.
• Base URL: https://discord.com/api/v10/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bot

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Discord is a good Harbor fit when we keep guild and channel targets explicit and keep message posting reviewable.

Good Harbor Discord actions:

• stable GET routes for guild discovery and guild-channel listing
• one explicit POST route for message creation
• Action Model input.path, input.query, and input.body envelopes instead of freeform URL editing
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for the bounded message body
• resultMode: "json_summary" for all starter actions

Avoid for now:

• attachment uploads and multipart file flows
• destructive moderation actions or channel mutation surfaces
• broad message-search or history actions that depend on privileged intents
• automatic publish of message-posting actions

Starter Discord actions

Automatic read actions

• list-guilds -> GET /users/@me/guilds
• list-channels -> GET /guilds/{guildId}/channels

Approval-friendly write actions

• create-message -> POST /channels/{channelId}/messages

Why these actions

These routes fit Harbor's current safe model because they:

• stay under one fixed Discord API origin
• use explicit guild and channel identifiers that operators supply at execution time
• keep optional query parameters typed and reviewable
• expose message posting as a named capability instead of arbitrary HTTP or raw credential access
• keep hidden auth entirely local to Harbor Node

Action Model notes

For Discord actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /users/@me/guilds
• /guilds/{guildId}/channels
• /channels/{channelId}/messages

At execution time, callers supply values by location:

• input.path for path placeholders
• input.query for typed query parameters
• input.body for JSON request bodies

Example guild listing request:

{
  "query": {
    "limit": 50,
    "with_counts": true
  }
}

Example channel listing request:

{
  "path": {
    "guildId": "123456789012345678"
  }
}

Example message create request:

{
  "path": {
    "channelId": "234567890123456789"
  },
  "body": {
    "content": "Release note draft ready for review.",
    "allowed_mentions": {
      "parse": []
    }
  }
}

Harbor fills path placeholders safely, validates query values against the stored schema, and keeps the request URL Harbor-owned.

Safety note for message posting

create-message stays on require_approval because Discord posts can notify users, trigger automations, and publish visible content in shared spaces. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the Discord Dock entry from Dock / Hub.
2. Configure the local Discord bot token in Harbor Node with the scopes and permissions you need.
3. Use list-guilds first to confirm the port is working.
4. Use list-channels to confirm the exact target guild and channel.
5. Keep create-message on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Discord Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path or bounded path-template actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Discord auth
• widen Discord into a generic arbitrary messaging or HTTP proxy

Current update strategy

For now, Discord updates are manual:

• update the Dock / Hub Discord integration document in apps/hub/catalog/integrations/discord/discord-bot-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as thread workflows, richer message composition, or moderation actions are intentionally deferred until Harbor has clearer policy controls for shared-channel writes.

Official reference starting points

• Discord developer docs root: https://docs.discord.com/developers
• Get current user guilds: https://docs.discord.com/developers/resources/user#get-current-user-guilds
• Get guild channels: https://docs.discord.com/developers/resources/guild#get-guild-channels
• Create message: https://docs.discord.com/developers/resources/message#create-message