DingTalk

Connect your GolemBot assistant to DingTalk using Stream mode (WebSocket). No public IP required.

Prerequisites

pnpm add dingtalk-stream

DingTalk Open Platform Setup

1. Go to DingTalk Developer Portal and create a robot application
2. Under Credentials, copy the Client ID (AppKey) and Client Secret (AppSecret)
3. Under Message Push, select Stream mode
4. Configure the bot's permissions as needed

Configuration

# golem.yaml
channels:
  dingtalk:
    clientId: ${DINGTALK_CLIENT_ID}
    clientSecret: ${DINGTALK_CLIENT_SECRET}

# .env
DINGTALK_CLIENT_ID=dingxxxxxxxxxx
DINGTALK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxx

How It Works

• Transport: Stream mode via DWClient from dingtalk-stream, using the TOPIC_ROBOT topic
• Events: Receives robot messages via the stream connection
• Reply: Posts response to data.sessionWebhook with x-acs-dingtalk-access-token header
• Chat types: Supports both DMs and group chats

Start

golembot gateway --verbose

The adapter connects to DingTalk's stream service on startup. Messages appear with [dingtalk] prefix when --verbose is enabled.

Group Chat

DingTalk server groups are treated as group chats. Configure the response policy via groupChat in golem.yaml:

groupChat:
  groupPolicy: mention-only  # recommended for DingTalk

Platform Limitation

DingTalk's Stream SDK (TOPIC_ROBOT) only delivers messages where the bot is @mentioned. Non-mention group messages are never sent to the bot process. This means:

• mention-only — works as expected
• smart — cannot observe non-mention messages for group context accumulation
• always — behaves the same as mention-only (platform-side filtering)

For best results, use mention-only with DingTalk.

Images and Files

The adapter downloads incoming images (picture / rich text messages) and file attachments so the agent can read them:

• Images: saved to the workspace and referenced in the prompt; multimodal engines can view them directly
• Files (PDF, HTML, code, etc.): saved to the workspace; the agent reads them with its file tools

Downloads use DingTalk's two-step media API (downloadCode → temporary URL → bytes), which requires the robot code. For enterprise internal robots the robot code equals the Client ID and is detected automatically; override it via robotCode in the channel config if yours differs:

channels:
  dingtalk:
    clientId: ${DINGTALK_CLIENT_ID}
    clientSecret: ${DINGTALK_CLIENT_SECRET}
    robotCode: ${DINGTALK_ROBOT_CODE}  # optional, defaults to clientId

Notes

• Stream mode uses outbound WebSocket — works behind NAT/firewalls
• Replies are sent to the session webhook URL provided in each incoming message
• The max message length is 4,000 characters; longer responses are automatically split