Python server SDK demo guide

This is a single-process web chat example: the browser talks to a FastAPI back end, which calls OpenAPI with AsyncDRClient, and signed callbacks drive live updates on the page. The Python SDK installs from PyPI, and the demo comes as a separate source ZIP; the front end is native ES modules, with no Node.js and no build step.

Download and prepare

Download the Python demo (1.0.0a2) · Download the SHA256 checksums

You need Python 3.11 or later, a reachable IM service, and the AppKey, Client ID and Client Secret of the same app. Chat between two accounts of the same app. You can create accounts in the console or through the demo's sign-up; password sign-in must be allowed by the app's policies.

Package layout:

deeprespond-im-python-demo-1.0.0a2/
├── README.md
├── requirements.txt
├── SHA256SUMS
└── demo/
    ├── __main__.py、main.py、app.py
    ├── 其他后端模块
    └── web/（HTML、CSS、原生 JavaScript 模块）

The ZIP has the demo and its dependency list; the SDK, FastAPI, Uvicorn, WebSocket and upload-parsing dependencies are installed with pip. It doesn't include the IM server, infrastructure or development and test tools.

Install and start

Unzip it, go into deeprespond-im-python-demo-1.0.0a2, and run:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

export IM_CLIENT_ID='替换为应用的 Client ID'
export IM_CLIENT_SECRET='替换为应用的 Client Secret'
python -m demo \
  --api http://127.0.0.1:18480 \
  --app-key '组织#应用' \
  --client-id "$IM_CLIENT_ID" --client-secret "$IM_CLIENT_SECRET" \
  --addr 127.0.0.1:8091 \
  --callback-credentials '回调地址ID:回调密钥'

Open http://127.0.0.1:8091. App credentials are passed as command-line arguments; the environment variables above are only for substitution in the terminal, and the demo doesn't read them itself. On Windows, run py -3.11 -m venv .venv and activate with .venv\Scripts\Activate.ps1. In PowerShell, put the start command on one line and write the environment variables in arguments as $env:IM_CLIENT_ID and $env:IM_CLIENT_SECRET.

Flag	Default or description
--api	http://127.0.0.1:18480, the IM service address
--app-key	Required, org#app
--client-id / --client-secret	Required, the same app's server credentials
--addr	127.0.0.1:8091, the address the demo listens on for the browser
--callback-credentials	endpointID:secret, comma-separated for several; without callbacks the page doesn't update live
--debug	Print debug logs, off by default

With the full repository, you can also run python -m pip install -r demo/requirements.txt in sdk/server/python and then python -m demo. Developing and checking the SDK source uses uv's development dependency group; see the demo README.

Configure live callbacks

1. In the console, create a callback endpoint for the app pointing to the demo's /im/callback, and save the endpoint ID and secret.
2. Put the endpoint ID and secret in --callback-credentials and start the demo.
3. Verify the endpoint in the console, and once it succeeds, turn on event subscriptions. The SDK's callback handler takes care of signature checks and URL verification.

The callback address must be reachable from the IM service. The browser opening the demo doesn't mean the IM service can send callbacks to it; for address rules, see the callback overview.

Subscribe to the events below, and also set filters.message_include_tips=true; a batch size of 10 events and a 5000-millisecond timeout are recommended:

message.sent, message.recalled, message.edited
friend.added, friend.removed, friend.updated, friend_request.received, blacklist.changed
group.created, group.info_changed, group.dismissed
group.members_added, group.members_removed, group.members_updated
user.profile_changed, user.sessions_revoked, user.relogin_required, presence.changed

Developing on your own machine needs the full IM repository. From the repository root, start a separate test service (harness):

make infra-up
go build -o /tmp/harness ./sdk/conformance/harness
/tmp/harness -env .env -addr 127.0.0.1:18580 -control 127.0.0.1:18590 \
  -db im_python_demo_test -redis-prefix python-demo-test:

Change the demo's --api to http://127.0.0.1:18580. The test service's control endpoints GET /env and GET /credentials return the test app's config, and it allows callbacks to local addresses. For the request format to create and verify callback endpoints through the control API, see the demo README.

Identities and permissions

Identity	Use	Where it's kept
App identity	The SDK uses the App Token to manage users, friends and groups and to send messages	The back end keeps the Client Secret and App Token
User's sign-in	The device sign-in a user gets by signing in with a password, used to read the history they can see, recall their own messages and change their password	The back end keeps the user's sign-in token (User Token), never sent to the browser
Browser session	The page reaches the demo through a cookie	The cookie maps to a session inside the demo process

The demo's back end does the checks below, and your own service needs them too:

• Every browser action first checks the user's sign-in; group operations read members and roles again each time.
• History is filtered per user when read (messages they deleted or cleared, messages from before they joined or after they left a group). The server SDK reads the full admin history, which mustn't be shown to users directly.
• Signing out revokes the real device sign-in; changing the password verifies the old one and replaces the token in one step, keeping the current device signed in.
• After edit and recall callbacks, messages are read again from the server, so a resent callback never brings back a message the user deleted.
• Attachments are only shown inline when their content is recognized as PNG, JPEG, GIF or WebP; everything else is sent as a download, with nosniff, a sandboxed CSP and no caching.

For the permission checks and attachment proxying your service needs, see Calling the API.

Features and structure

It demonstrates sign-up and sign-in, one-to-one and group chat, text, images and files, quote replies, scrolling back through history, read status, recall, per-user delete and clear, friends and blocklists, group management, profiles and device management. Typing indicators are only relayed within the demo process; client-only features such as reactions, pinning, and accepting or declining friend requests and group invitations show a clear notice in the UI.

File	Responsibility
main.py, __main__.py	Parsing arguments, creating the SDK client and starting
app.py	HTTP, WebSocket, static assets and attachments
state.py, views.py	State and the data returned to the page
actions.py, data.py, client_api.py	Page actions, permissions, and APIs called as the user
callbacks.py, bridge.py	Handling callbacks, pushing to the browser, cleaning up sessions
web/	Native page modules, with no build step

Every source file stays under 500 lines, and structure tests check file length and module dependencies. Sessions, tokens and caches live in process memory, so users sign in again after a restart. Use different browsers or a private window for the two accounts; both the Python and Go demos use the demo_sid cookie, and cookies aren't separated by port.

Troubleshooting and regression tests

Symptom	Check
No module named demo	Whether you run it from the unzipped root and demo/__main__.py exists
Missing runtime dependencies	Activate the virtual environment and reinstall the package's requirements.txt
App credentials reported missing	Whether the matching arguments were passed explicitly; the demo doesn't read environment variables itself
Sign-in fails	The IM address, app, username and password, and whether password sign-in is allowed
Endpoint verification fails	Whether the demo is running, the IM service can reach the callback address, and the endpoint ID and secret match
Sending works but the page doesn't update live	Whether the endpoint is verified, events are subscribed, and the signing secret is right
Sign-ins in two windows overwrite each other	Use different browsers or a private window; different ports don't separate cookies
Signed out after a restart	State lives only in process memory; just sign in again

Running the demo ZIP doesn't need pytest, Playwright or the SDK's development tools. SDK checks, security regression tests against a real service, and screenshot end-to-end tests run in the full repository; for the commands and isolation requirements, see the demo README.