XuqmGroup-Web/docs-site/docs/server/python-sdk.md

Python Server SDK

XuqmGroup 服务端 Python SDK，封装了：

• IM 账号、UserSig 生成与登录、消息、群组、好友、会话、黑名单
• 管理端 Webhook、操作日志
• Push 注册与推送

---

安装

pip install xuqmgroup-server-sdk-python

---

初始化

from xuqm_im_server_sdk import XuqmImServerSdk

sdk = XuqmImServerSdk(
    base_url="https://dev.xuqinmin.com",
    app_key="your_app_key",
    app_secret="your_app_secret",
)

服务端 SDK 需要 app_secret 用于 HMAC 签名，app_secret 绝不下发到客户端。

---

UserSig

user_sig = sdk.generate_user_sig("user_001")
valid = sdk.verify_user_sig("user_001", user_sig)
login = sdk.login_with_user_sig("user_001", user_sig)

管理员账号可用于服务端 SDK / 管理端 REST API。

---

能力分类

分类	主要方法
登录	generate_user_sig, verify_user_sig, login, login_with_user_sig
账号	import_account, import_accounts, delete_account, get_profile, update_profile, search_accounts, check_account
消息	send_message, revoke_message, edit_message, fetch_history, fetch_group_history, search_messages
会话	list_conversations, set_conversation_pinned, set_conversation_muted, mark_read, set_draft, set_conversation_hidden, set_conversation_group, delete_conversation
好友	list_friends, add_friend, add_friends, remove_friend, remove_friends, remove_all_friends, set_friend_group, list_friend_groups, list_friends_by_group, check_friends
黑名单	list_blacklist, add_blacklist, remove_blacklist, check_blacklist
群组	list_groups, list_public_groups, search_groups, get_group, list_group_members, search_group_members, create_group, update_group, add_group_member, add_group_members, remove_group_member, remove_group_members, set_group_role, transfer_group_owner, leave_group, update_group_attributes, remove_group_attributes, mute_group_member, dismiss_group, send_group_join_request, list_group_join_requests, accept_group_join_request, reject_group_join_request, accept_group_join_requests, reject_group_join_requests
管理端	query_user_state, kick_users, batch_send_message, admin_set_msg_read, import_messages, admin_transfer_group_owner, admin_update_group_attributes, admin_remove_group_attributes, admin_group_read_receipts
Webhook	list_webhooks, create_webhook, update_webhook, delete_webhook, verify_callback_signature, parse_callback_envelope
Push	register_push_token, send_push, push_user_status, push_device_logs, test_offline_push

---

发送消息

msg = sdk.send_message(
    to_id="user_002",
    chat_type="SINGLE",
    msg_type="TEXT",
    content="Hello from Python SDK!",
)
print(f"消息已发送: {msg['id']}")

发送群消息

msg = sdk.send_message(
    to_id="group_xxx",
    chat_type="GROUP",
    msg_type="TEXT",
    content="大家好",
)

撤回消息

sdk.revoke_message("message_id")

---

群管理

group = sdk.create_group(
    name="项目讨论",
    member_ids=["user_001", "user_002"],
)

sdk.add_group_member("group_xxx", "user_003")
sdk.remove_group_member("group_xxx", "user_003")

groups = sdk.list_groups()
members = sdk.list_group_members("group_xxx")

---

Push 推送

sdk.send_push(
    user_id="user_001",
    title="新消息",
    body="你有一条未读消息",
    payload={"chatId": "user_002"},
)

---

错误处理

SDK 在请求失败时会抛出 XuqmAPIError 异常：

from xuqm_im_server_sdk import XuqmAPIError

try:
    msg = sdk.send_message(to_id="user_002", chat_type="SINGLE", msg_type="TEXT", content="Hello")
except XuqmAPIError as e:
    print(f"API 错误: status={e.status}, code={e.code}, message={e.message}")

→ Server API 文档