DingTalk Bot

Complete DingTalk bot integration for AI agents.

Features

1. Messaging

• Send text, markdown, link, and action card messages
• Send to groups via webhook or API
• At mentions and notifications

2. Group Management

• Create groups
• Add/remove members
• Group robot management

3. Approval Workflows

• Create approval instances
• Query approval status
• Approval callbacks

4. Attendance

• Get attendance records
• Query employee attendance
• Vacation balance

Prerequisites

1. Create a DingTalk Corp at https://open.dingtalk.com
2. Create a Custom Robot in group settings
3. Get Webhook URL and Secret (for signature verification)
4. For advanced features, create an internal app and get AppKey/AppSecret

Configuration

Set environment variables:

# For webhook-based bots
export DINGTALK_WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=xxx"
export DINGTALK_SECRET="SECxxx"

# For API-based bots
export DINGTALK_APP_KEY="ding_xxx"
export DINGTALK_APP_SECRET="xxx"
export DINGTALK_AGENT_ID="xxx"

Usage

Send Text Message (Webhook)

from dingtalk_bot import DingTalkBot

# Webhook mode
bot = DingTalkBot(webhook_url="YOUR_WEBHOOK_URL", secret="YOUR_SECRET")

# Send text
bot.send_text("Hello from bot!")

# Send with at mentions
bot.send_text("Hello @all", at_mobiles=["13800138000"])

Send Markdown Message

bot.send_markdown(
    title="Daily Report",
    text="## Sales Report\n- Today: $10,000\n- Week: $50,000"
)

Send Action Card

bot.send_action_card(
    title="Approval Request",
    text="Please approve the following request",
    buttons=[
        {"title": "Approve", "action_url": "https://.../approve"},
        {"title": "Reject", "action_url": "https://.../reject"}
    ]
)

Create Group (API Mode)

# API mode with authentication
bot = DingTalkBot(app_key="xxx", app_secret="xxx", agent_id="xxx")

group = bot.create_group(name="Project Team", owner_user_id="manager123")
print(group["open_conversation_id"])

Approval Workflow

# Create approval
approval = bot.create_approval(
    process_code="PROC-xxx",
    originator_user_id="user123",
    form_values={"title": "Leave Request", "days": 3}
)

# Get status
status = bot.get_approval_instance(approval["process_instance_id"])

Attendance Query

records = bot.get_attendance_records(
    work_date="2024-03-15",
    user_ids=["user123", "user456"]
)
print(records)

API Reference

Webhook Methods

API Methods

Signature Generation

For webhook security, generate signature:

import hmac
import hashlib
import base64
import time

timestamp = str(round(time.time() * 1000))
secret = "YOUR_SECRET"

string_to_sign = f'{timestamp}\n{secret}'
sign = hmac.new(string_to_sign.encode('utf-8'), digestmod=hashlib.sha256).digest()
signature = base64.b64encode(sign).decode('utf-8')

Error Handling

Common errors:

• 400031: Invalid signature - check secret
• 400035: Missing parameters - verify request body
• 400036: Invalid approval process - check process_code
• 400037: Duplicate approval - instance already exists

Links

• DingTalk Open Platform
• API Documentation
• Robot Development