How to Add an AI Assistant to DingTalk? 3 Approaches Compared (With Stream Mode Code)

There are three ways to wire AI into DingTalk — picking wrong doesn't just mean more code, it means messages that never arrive, rate limits, or a data boundary you can't explain to compliance

TL;DR Table: The Three Approaches

One line: conversations need A, notifications fit B, quick validation uses C. The classic mistakes: trying to build a chatbot on B (it can't receive group messages), or jumping to C without checking the data boundary.

Approach A: Internal Enterprise App Robot + Stream Mode (Recommended)

This is DingTalk's recommended path: your service uses Stream mode to dial out and hold a WebSocket long connection to DingTalk. An employee messages the robot → DingTalk pushes the message down that connection → your service calls the AI → the reply goes back up the same connection. Because there is no inbound HTTP callback, you need no public IP, no registered domain, and no inbound firewall port — it runs fine on an intranet-only machine. That is the big difference from the HTTP-callback route.

# dingtalk_stream_bot.py — open a long connection and subscribe to robot messages
from dingtalk_stream import DingTalkStreamClient, Credential
from dingtalk_stream.chatbot import ChatbotHandler, ChatbotMessage

class AIHandler(ChatbotHandler):
    async def process(self, callback):
        msg = ChatbotMessage.from_dict(callback.data)
        # ack first, process asynchronously — never wait for the AI inside the callback (Pitfall 3)
        self.reply_text("Got it, working on it…", msg)
        question = msg.text.content.strip()
        answer = ask_ai(question)          # your own AI service / knowledge base
        self.reply_text(answer, msg)
        return 200, "OK"

credential = Credential(CLIENT_ID, CLIENT_SECRET)      # read from env vars, never hardcode
client = DingTalkStreamClient(credential)
client.register_callback_handler("/v1.0/im/bot/messages/get", AIHandler())
client.start_forever()                 # has built-in reconnect, but still needs process supervision

# dingtalk_client.py — centralized token cache + send robot message
import time, requests

_token, _ts = "", 0

def get_token():
    global _token, _ts
    if _token and time.time() - _ts < 7000:          # 200s safety margin
        return _token
    r = requests.post("https://api.dingtalk.com/v1.0/oauth2/accessToken",
                      json={"appKey": CLIENT_ID, "appSecret": CLIENT_SECRET},
                      timeout=5).json()
    _token, _ts = r["accessToken"], time.time()
    return _token

def reply_text(user_id, text):
    requests.post(
        "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend",
        headers={"x-acs-dingtalk-access-token": get_token()},
        json={"robotCode": ROBOT_CODE, "userIds": [user_id],
              "msgKey": "sampleText", "msgParam": '{"content": "%s"}' % text[:1800]},
        timeout=5)

Approach B: Custom Group Robot Webhook (10 minutes, push-only)

Group settings → "Smart Group Assistant" → "Add Robot" → "Custom" gives you a webhook URL. POST JSON to it and the message lands in the group (optional signed verification):

curl 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"text","text":{"content":"Deploy done: order service v2.3 is live"}}'

Its role is one-way notification: monitoring alerts, CI/CD results, daily digests. Three hard limits: it cannot receive group messages (no conversations), each robot has a per-minute send cap (high-frequency alerts must be aggregated), and @-mentions need a phone number or userId (not a display name). Text, markdown, link, and actionCard types are supported. Good for "tell humans what the system did" — wrong for "humans ask, system answers".

Approach C: Third-Party SaaS (fastest — but check the data boundary first)

Managed platforms let you authorize DingTalk and configure a knowledge base from a web console — no long-connection code to write, live within half a day. Two situations fit: no dev capacity, or you want to validate the value of an AI assistant before committing engineering time.

But ask four questions before signing, or you'll pay for it later:

1. Where is data stored: do employee questions and uploaded documents live on their platform? In which region?
2. Can you export: if you switch later, can the knowledge base and conversation history leave with you?
3. Is on-prem possible: after validation, can it migrate to the self-hosted Approach A form?
4. How is it billed: per seat or per call? Who pays the underlying LLM cost?

Side by Side: DingTalk vs Feishu vs WeCom — Where the Effort Actually Goes

Conclusion: if your intranet restricts outbound traffic and you don't want to apply for a public domain just for callbacks, DingTalk's Stream mode is the easiest of the three to land. WeCom's 5-second callback limit needs the most engineering cushioning; Feishu sits in between. When you integrate several platforms, extract "receive → call AI → reply" into one shared gateway and keep platform differences in an adapter layer — otherwise adding the next platform means starting over.

Five Common Pitfalls and Fixes

Pre-Launch Checklist (8 items)

1. Does the long connection auto-reconnect, with process supervision that restarts it on exit?
2. Is there a liveness probe — a periodic heartbeat that alerts past a threshold?
3. Is message dedup in place (Redis/in-memory), shared across instances?
4. Is access_token centrally cached, refreshed under lock, with expiry margin?
5. Does the AI call have a timeout fallback (ack first, then a notice — never leave users hanging)?
6. Are long replies split or summarized, and is msgParam serialized rather than hand-built?
7. Is there sensitive-word/permission filtering before sending, and is robot visibility scoped by department?
8. Are logs sanitized and Client Secrets kept in environment variables instead of the codebase?

Final Thoughts

No approach is universally better — the choice comes down to three things: how strict your data boundary is, how much dev capacity you have, and what scenario you're solving. Don't spend engineering on Approach A for a notification feed; don't build a chatbot on Approach B (it can't receive); don't sign up for Approach C without asking the four data-boundary questions. Many teams' real path: validate quickly with C or B, then migrate to A as the long-term self-hosted home.

If you only keep one line: conversations → A, notifications → B, validation → C — don't mix them.