Moltbot Dingtalk

Name: Moltbot Dingtalk
Rating: 3.5 (1 reviews)
Author: cacotopia

By cacotopia ⭐ 6 stars 👁 3 views ▲ 0 votes

Moltbot DingTalk channel plugin

GitHub

Install

npm install @moltbot/dingtalk

Configuration Example

channels:
  dingtalk:
    enabled: true
    clientId: "your_client_id"
    clientSecret: "secret"
    # Connection mode: "websocket" (recommended) or "callback"
    connectionMode: "websocket"
    # DM policy: "pairing" | "open" | "allowlist"
    dmPolicy: "pairing"
    # Group policy: "open" | "allowlist" | "disabled"
    groupPolicy: "allowlist"
    # Require @mention in groups
    requireMention: true
    # Max media size in MB (default: 30)
    mediaMaxMb: 30
    # Render mode for bot replies: "auto" | "raw" | "card"
    renderMode: "auto"

README

# moltbot-dingtalk

DingTalk/Lark (钉钉) channel plugin for [Moltbot](https://github.com/moltbot/moltbot).

## Installation

```bash
moltbot plugins install @moltbot/dingtalk
```

Or install via npm:

```bash
npm install @moltbot/dingtalk
```

## Configuration

1. Create a custom robot app on [DingTalk Developer Platform](https://open-dev.dingtalk.com/)
2. Get your App Key and App Secret from the app dashboard
3. Enable required permissions (see below)
4. **Configure event subscriptions** (see below) ⚠️ Important
5. Configure the plugin:

### Required Permissions

| Permission | Scope | Description |
|------------|-------|-------------|
| `im:messages:read` | Messaging | Read messages |
| `im:messages:write` | Messaging | Send messages |
| `contact:read` | Contact | Get user information |

### Event Subscriptions ⚠️

> **This is the most commonly missed configuration!** If the bot can send messages but cannot receive them, check this section.

In the DingTalk Developer Platform console, go to **Event Subscription**:

1. **Event Configuration**: Select **Callback** or **Stream** mode
2. **Add Event Subscriptions**:

| Event | Description |
|-------|-------------|
| `user_im_message_received_v1` | Receive messages (required) |
| `group_message_received_v1` | Receive group messages |
| `user_join_group_v1` | User joined group |
| `user_leave_group_v1` | User left group |

3. Ensure the event permissions are approved

```bash
moltbot config set channels.dingtalk.clientId "your_client_id"
moltbot config set channels.dingtalk.clientSecret "your_client_secret"
moltbot config set channels.dingtalk.enabled true
```

### Configuration Options

```yaml
channels:
  dingtalk:
    enabled: true
    clientId: "your_client_id"
    clientSecret: "secret"
    # Connection mode: "websocket" (recommended) or "callback"
    connectionMode: "websocket"
    # DM policy: "pairing" | "open" | "allowlist"
    dmPolicy: "pairing"
    # Group policy: "open" | "allowlist" | "disabled"
    groupPolicy: "allowlist"
    # Require @mention in groups
    requireMention: true
    # Max media size in MB (default: 30)
    mediaMaxMb: 30
    # Render mode for bot replies: "auto" | "raw" | "card"
    renderMode: "auto"
```

#### Render Mode

| Mode | Description |
|------|-------------|
| `auto` | (Default) Automatically detect: use card for messages with code blocks or tables, plain text otherwise. |
| `raw` | Always send replies as plain text. Markdown tables are converted to ASCII. |
| `card` | Always send replies as interactive cards with full markdown rendering (syntax highlighting, tables, clickable links). |

## Features

- WebSocket and Callback connection modes
- Direct messages and group chats
- Message replies and quoted message context
- **Inbound media support**: AI can see images, read files (PDF, Excel, etc.), and process rich text with embedded images
- Image and file uploads (outbound)
- Typing indicator (via emoji reactions)
- Pairing flow for DM approval
- User and group directory lookup
- **Card render mode**: Optional markdown rendering with syntax highlighting

## FAQ

#### Bot cannot receive messages

Check the following:
1. Have you configured **event subscriptions**? (See Event Subscriptions section)
2. Is the event configuration set to **websocket** or **callback**?
3. Did you add the `user_im_message_received_v1` event?
4. Are the permissions approved?

#### 403 error when sending messages

Ensure `im:messages:write` permission is approved.

#### How to clear history / start new conversation

Send `/new` command in the chat.

#### Why is the output not streaming

DingTalk API has rate limits. Streaming updates can easily trigger throttling. We use complete-then-send approach for stability.

---

## License

MIT

channels