---
id: dingtalk-stream
version: "0.24.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# dingtalk-stream — A Python library for sending messages to DingTalk chatbot

License: permissive · Maintenance: active · Downloads: 794.0K/mo

## What it is and what it does

dingtalk-stream is a Python SDK that implements DingTalk's Stream Mode protocol for building chatbots and event handlers. Instead of polling or managing webhooks, it opens a persistent WebSocket connection to DingTalk's servers and receives events (messages, callbacks, card interactions) asynchronously. You define handler classes that process incoming events and send replies back through the same connection.

The SDK wraps the async complexity: you write a handler class with a process() method, register it with a DingTalkStreamClient, and call start_forever() to begin listening. It handles credential management, WebSocket lifecycle, and message acknowledgment. The library depends on aiohttp, requests, and websockets for its HTTP and WebSocket transport layers.

Use it for:

- Build a DingTalk chatbot that responds to user messages in real time without setting up external webhooks or polling.
- Handle card callback events (button clicks, form submissions) from DingTalk cards sent by your application.
- Integrate DingTalk event notifications into an existing asyncio application using client.start() instead of start_forever().
- Process multiple event types (messages, callbacks, approvals) by registering different handler classes for each topic.
- Deploy a stateless bot that maintains a single persistent connection to DingTalk rather than multiple HTTP endpoints.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Python SDK for building DingTalk chatbots and event handlers using Stream Mode, which connects to DingTalk's messaging and callback APIs via WebSocket.

Yes, if you are building a DingTalk chatbot or event handler in Python. The SDK is actively maintained, has low install friction, uses a permissive MIT license, and is classified as Alpha development status. No known vulnerabilities. The main gotcha is that you must obtain DingTalk credentials and understand that Stream Mode requires a persistent WebSocket connection rather than stateless HTTP webhooks.

## Install

pip install dingtalk-stream
uv add dingtalk-stream
poetry add dingtalk-stream

## Installing dingtalk-stream

Before you install: Low install friction with a pure-Python wheel. Actively maintained as of 2026-07-30 with 173 repository stars. Depends on aiohttp, requests, and websockets for async HTTP and WebSocket communication.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install dingtalk-stream

import dingtalk_stream

credential = dingtalk_stream.Credential(client_id, client_secret)
client = dingtalk_stream.DingTalkStreamClient(credential)
client.register_callback_handler(dingtalk_stream.chatbot.ChatbotMessage.TOPIC, handler)
client.start_forever()

Requires DingTalk app credentials (client_id and client_secret) from https://open-dev.digntalk.com; Stream Mode connection is WebSocket-based and requires network access to DingTalk servers.

Verify before relying:

- Whether Python 3.6 and 3.7 support (listed in classifiers) is actively tested or maintained given the active status.
- Performance characteristics under high message volume or concurrent callback handlers.
- Whether the package handles automatic reconnection and backoff after network failures, or if manual restart is always required.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 794.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

dingtalk chatbot sdk, dingtalk stream mode, dingtalk event handler, dingtalk webhook alternative, dingtalk message callback, dingtalk bot python, dingtalk-integration, chatbot-framework, websocket-client

[View on SkillFed](https://skillfed.io/packages/dingtalk-stream) · [View on PyPI](https://pypi.org/project/dingtalk-stream/)