openclaw/docs/channels/kakao.md

title	description
KakaoWork	Connect Moltbot to KakaoWork for Korea-focused enterprise messaging

KakaoWork

Connect Moltbot to KakaoWork, Korea's leading enterprise messaging platform.

KakaoWork is available as a third-party plugin. Install with: ```bash moltbot plugins install @hanishkeloth/moltbot-kakao ```

Features

• Direct message conversations via KakaoWork Bot API
• Reactive callback handling for button interactions
• Multi-account configuration support
• Pairing-based DM access control
• Rate limit aware (200 req/min workspace limit)

Prerequisites

1. KakaoWork workspace admin access
2. Bot created in KakaoWork Admin Console
3. Bot App Key

Getting Your App Key

1. Go to KakaoWork Admin Console
2. Navigate to 봇 관리 (Bot Management)
3. Click 봇 추가 (Add Bot) or select existing bot
4. Copy the App Key from bot settings

Installation

moltbot plugins install @hanishkeloth/moltbot-kakao

Configuration

Using Environment Variable

export KAKAOWORK_APP_KEY="your-app-key-here"

Using Config File

Add to ~/.config/moltbot/config.jsonc:

{
  "channels": {
    "kakao": {
      "enabled": true,
      "appKey": "your-app-key-here",
      "dmPolicy": "pairing"
    }
  }
}

Configuration Options

Option	Type	Default	Description
appKey	string	-	Bot App Key from KakaoWork admin
keyFile	string	-	Path to file containing app key
callbackUrl	string	-	HTTPS URL for reactive events
callbackPath	string	-	Gateway HTTP path for callbacks
dmPolicy	string	"pairing"	Access policy (see below)
allowFrom	array	[]	User IDs allowed to DM the bot
proxy	string	-	Proxy URL for API requests

DM Policies

Policy	Description
pairing	Users must pair with a code before chatting (default)
allowlist	Only users in allowFrom list can chat
open	Anyone in workspace can chat
disabled	DMs are disabled

Multi-Account Setup

For multiple KakaoWork bots:

{
  "channels": {
    "kakao": {
      "enabled": true,
      "accounts": {
        "support": {
          "appKey": "SUPPORT_BOT_APP_KEY",
          "dmPolicy": "open"
        },
        "internal": {
          "appKey": "INTERNAL_BOT_APP_KEY",
          "dmPolicy": "allowlist",
          "allowFrom": ["12345", "67890"]
        }
      },
      "defaultAccount": "support"
    }
  }
}

Callback URL (Reactive Events)

To receive button interactions and modal submissions:

1. Set up HTTPS endpoint (use ngrok for testing)
2. Configure callback URL:

{
  "channels": {
    "kakao": {
      "callbackUrl": "https://your-domain.com/kakao/callback",
      "callbackPath": "/kakao/callback"
    }
  }
}

3. Register the callback URL in KakaoWork Admin Console

Sending Messages

# Send to conversation ID
moltbot message send --channel kakao --to 123456789 --message "Hello!"

# Using the agent
moltbot agent --message "Say hello" --channel kakao

Pairing Flow

When dmPolicy: "pairing" (default):

1. User sends message to bot
2. Bot replies with pairing code
3. Admin approves: moltbot pairing approve kakao <user-id>
4. User can now chat freely

Rate Limits

KakaoWork enforces 200 requests per minute at the workspace level. The plugin handles rate limiting automatically, but be aware when sending bulk messages.

Troubleshooting

"Invalid authentication" error

• Check your App Key is correct
• Verify bot is activated in KakaoWork Admin

Messages not sending

• Ensure bot has permission to message the user
• Check if rate limit (200/min) is exceeded
• Verify conversation exists (use conversations.open first)

Callback not receiving events

• Callback URL must be HTTPS
• Check firewall allows incoming connections
• Verify callback URL registered in KakaoWork Admin

API Reference

This plugin uses the KakaoWork Web API:

• bots.info - Get bot information
• conversations.open - Create/open DM conversations
• conversations.list - List bot conversations
• messages.send - Send messages

Links

• KakaoWork Developer Docs
• Plugin Repository
• npm Package