playbooks

home / skills / xiaomingx / moltbot-connector-feishu-dingtalk / dingtalk-connection

dingtalk-connection skill

/skills/dingtalk-connection

This skill bridges DingTalk outgoing webhooks to Clawdbot Gateway, enabling reliable messaging and troubleshooting for DingTalk channels.

npx playbooks add skill xiaomingx/moltbot-connector-feishu-dingtalk --skill dingtalk-connection

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
1.3 KB
---
name: dingtalk-connection
description: Bridge DingTalk outgoing webhook messages to Clawdbot Gateway and send replies back to DingTalk sessions. Use when setting up DingTalk as a messaging channel, troubleshooting webhook delivery, or running the local bridge service.
---

# DingTalk Bridge

Bridge DingTalk bot messages to Clawdbot Gateway over a local WebSocket connection.

## Architecture

```
DingTalk user -> DingTalk cloud -> webhook (bridge.py) -> Clawdbot Gateway -> AI agent
```

## Setup

### 1. Create DingTalk bot

Create a bot that can send outgoing webhooks and set the callback URL to your public endpoint.

### 2. Run bridge

```bash
cd <skill-dir>/dingtalk-connection
uv sync
DINGTALK_SIGNING_SECRET=your_secret uv run python bridge.py
```

### 3. Auto-start (macOS)

```bash
uv run python setup_service.py
launchctl load ~/Library/LaunchAgents/com.clawdbot.dingtalk-bridge.plist
```

## Environment variables

| Variable | Required | Default |
|---|---|---|
| `DINGTALK_PORT` | — | `3210` |
| `DINGTALK_PATH` | — | `/dingtalk` |
| `DINGTALK_SIGNING_SECRET` | — | — |
| `DINGTALK_BOT_ID` | — | — |
| `DINGTALK_BOT_NAME` | — | — |
| `CLAWDBOT_CONFIG_PATH` | — | `~/.clawdbot/clawdbot.json` |
| `CLAWDBOT_AGENT_ID` | — | `main` |
| `DINGTALK_THINKING_THRESHOLD_MS` | — | `2500` |

Overview

This skill bridges DingTalk outgoing webhook messages to a Clawdbot Gateway and relays replies back into DingTalk sessions. It runs a local HTTP endpoint that validates DingTalk signatures, forwards user events to Clawdbot over WebSocket, and returns agent responses to the originating DingTalk conversation. Use it to add DingTalk as a messaging channel for an AI agent or run a local bridge for development and troubleshooting.

How this skill works

The bridge receives DingTalk webhook callbacks on a configurable HTTP path and port, verifies the request using the DingTalk signing secret, and forwards the event to a running Clawdbot Gateway via a local WebSocket connection. The Clawdbot agent processes the message and the bridge posts the generated reply back into the DingTalk session. It supports running as a foreground process or as a macOS launchd service for auto-start.

When to use it

  • When adding DingTalk as a messaging channel for an existing Clawdbot agent.
  • During local development to test DingTalk-to-agent message flow.
  • When troubleshooting webhook delivery, signature validation, or reply routing.
  • To run a resilient local bridge with auto-start on macOS.
  • When you need a minimal, configurable connector without full cloud hosting.

Best practices

  • Keep DINGTALK_SIGNING_SECRET private and set it in the environment before starting the bridge.
  • Expose a stable public callback URL (use a reverse proxy or tunnel) so DingTalk can reach the bridge.
  • Set DINGTALK_PORT and DINGTALK_PATH to avoid conflicts with other local services.
  • Run the bridge as a service (macOS launchd or systemd) in production to ensure uptime.
  • Monitor webhook delivery logs and Clawdbot Gateway connection state to catch dropped messages quickly.

Example use cases

  • Connect an internal AI assistant to DingTalk so employees can ask questions from chat.
  • Run the bridge locally while iterating on agent prompts and observe live responses in DingTalk.
  • Validate webhook signature handling during a security audit of messaging integrations.
  • Automatically restart the bridge on macOS by installing it as a launchd service.
  • Troubleshoot message latency by adjusting DINGTALK_THINKING_THRESHOLD_MS and observing behavior.

FAQ

What environment variables are required to run the bridge?

At minimum set DINGTALK_SIGNING_SECRET to validate incoming webhooks. Configure DINGTALK_PORT, DINGTALK_PATH, DINGTALK_BOT_ID, and CLAWDBOT_AGENT_ID as needed; defaults exist for several values.

How do I test the bridge locally when DingTalk needs a public callback URL?

Use a tunneling tool (for example, ngrok) or configure a reverse proxy on a public host to forward DingTalk traffic to your local DINGTALK_PORT and DINGTALK_PATH.