{ "openapi": "3.1.0", "info": { "title": "WeChat Cloud Capability API", "version": "0.1.0", "description": "Cloud protocol capability API for personal WeChat accounts, media resources, Finder, workers, and object storage entitlements." }, "servers": [ { "url": "https://weixin.uaisir.com", "description": "WeChat cloud capability API root" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/chatrooms": { "get": { "summary": "Reserved enterprise WeChat chatrooms query", "operationId": "listEnterpriseWechatChatrooms", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Reserved for enterprise WeChat capability surface." } }, "tags": [ "Enterprise WeChat Reserved" ], "description": "Reserved enterprise WeChat chatrooms query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled." } }, "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/contacts": { "get": { "summary": "Reserved enterprise WeChat contacts query", "operationId": "listEnterpriseWechatContacts", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Reserved for enterprise WeChat capability surface." } }, "tags": [ "Enterprise WeChat Reserved" ], "description": "Reserved enterprise WeChat contacts query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled." } }, "/api/capabilities/enterprise-wechat/v1/accounts/{accountId}/external-contacts": { "get": { "summary": "Reserved enterprise WeChat external contacts query", "operationId": "listEnterpriseWechatExternalContacts", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "description": "Reserved for enterprise WeChat capability surface." } }, "tags": [ "Enterprise WeChat Reserved" ], "description": "Reserved enterprise WeChat external contacts query. Reserved enterprise WeChat capability endpoint. It keeps the API Fox and generated-client namespace stable before the independent enterprise WeChat implementation is enabled." } }, "/api/capabilities/personal-wechat/v1/accounts": { "get": { "summary": "List cloud-mounted WeChat accounts", "operationId": "listPersonalWechatAccounts", "responses": { "200": { "description": "Account list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatAccount" } } } } } }, "examples": { "default": { "value": { "data": { "items": [ { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "protocolDeviceType": "ipad", "status": "bound", "online": true, "nickname": "客服微信一号", "avatarUrl": "", "updatedAt": "2026-07-05T00:00:00.000Z" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "List cloud-mounted WeChat accounts. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." }, "post": { "summary": "Create pending WeChat account record", "operationId": "createPersonalWechatAccount", "responses": { "200": { "description": "Pending account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatAccount" } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_pending_example", "displayName": "客服微信一号", "status": "pending_bind", "mode": "cloud", "runtime": { "state": "pending_bind" }, "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Create pending WeChat account record. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatAccountCreateRequest" }, "examples": { "default": { "value": { "displayName": "客服微信一号", "deviceId": "macbook-pro-local" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/actions/validate": { "post": { "summary": "Validate an account action before execution", "operationId": "validateAction", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Action validation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatActionValidationResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "action": "message.send_text", "targetId": "wxid_example", "allowed": true, "requiredCapability": "action.execute", "riskLevel": "low", "requiresProposal": false, "reason": "" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Tasks" ], "description": "Validate an account action before execution. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatActionValidateRequest" }, "examples": { "default": { "value": { "action": "message.send_text", "targetId": "wxid_example", "reason": "manual-send" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/bind-sessions": { "post": { "summary": "Create cloud QR bind session", "operationId": "createBindSession", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Bind session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatBindSessionResponse" }, "examples": { "default": { "value": { "data": { "bindSessionId": "bind_example", "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "hostDeviceId": "macbook-pro-local", "cloudKeyId": "key_slot_example", "wechatKeyId": "key_slot_example", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "allowedProtocolDeviceTypes": [ "ipad" ], "defaultProtocolDeviceType": "ipad", "allowProtocolDeviceSwitch": false, "seatIndex": 1, "seatId": "seat_example", "proxyRequired": false, "proxyBypassed": false, "proxyLease": {}, "entitlement": {}, "status": "issued", "lastEvent": "created", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Create cloud QR bind session. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatBindSessionCreateRequest" }, "examples": { "default": { "value": { "deviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "localAccountCount": 0 } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/capabilities": { "get": { "summary": "Get account capability directory", "operationId": "getAccountCapabilities", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Account capability directory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatCapabilityDirectoryResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "mode": "cloud", "available": [ "wechat.bind", "action.execute" ], "unavailable": [], "runtime": { "status": "available", "health": "online", "workerId": "worker-mac-1" }, "storage": { "objectStorageEnabled": true, "storageAvailableBytes": 1073741824, "maxFileSizeBytes": 104857600 }, "notes": [ "公开能力 API 只返回产品层账号和脱敏状态，不返回 WeChat Key、登录态、代理凭证或原始协议响应。" ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Get account capability directory. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts": { "get": { "summary": "List contacts from cloud event cache", "operationId": "listContacts", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Contact list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatContactPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "cursor": 42, "items": [ { "accountId": "wacct_example", "contactId": "wxid_example", "targetId": "wxid_example", "userName": "wxid_example", "nickname": "张三", "remarkName": "", "alias": "", "avatarUrl": "", "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "source": "cloud_event_cache", "syncRequired": true } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "List contacts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/details": { "post": { "summary": "Create contact details task", "operationId": "createContactDetailsTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Contact details task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "contacts_details_example", "type": "contacts_details", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Create contact details task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/search": { "get": { "summary": "Search contacts from cloud event cache", "operationId": "searchContacts", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Contact search result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatContactPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "cursor": 42, "items": [ { "accountId": "wacct_example", "contactId": "wxid_example", "targetId": "wxid_example", "userName": "wxid_example", "nickname": "张三", "remarkName": "", "alias": "", "avatarUrl": "", "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "source": "cloud_event_cache", "syncRequired": true } ], "query": "张三" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Search contacts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." }, "post": { "summary": "Create protocol contact search task", "operationId": "createContactSearchTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Contact search task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "contacts_search_example", "type": "contacts_search", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Create protocol contact search task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/contacts/sync": { "post": { "summary": "Create contact sync task", "operationId": "createContactSyncTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Contact sync task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "contacts_sync_example", "type": "contacts_sync", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Create contact sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/conversations": { "get": { "summary": "List conversations from cloud event cache", "operationId": "listConversations", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Conversation list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatConversationPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "cursor": 42, "items": [ { "targetId": "wxid_example", "displayName": "张三", "conversationType": "contact", "messageType": "text", "previewText": "已脱敏消息预览", "lastCursor": 42, "updatedAt": "2026-07-05T00:00:00.000Z", "unreadCount": 0 } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Conversations" ], "description": "List conversations from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/conversations/{targetId}/messages": { "get": { "summary": "List normalized conversation messages", "operationId": "listConversationMessages", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/targetId" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Normalized conversation messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatMessagePageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "targetId": "wxid_example", "conversationType": "contact", "source": "cloud_event_cache", "syncRequired": true, "schemaVersion": "wechat.protocol.normalized-messages.v1", "cursor": 42, "nextCursor": 42, "hasMore": false, "items": [ { "eventId": "evt_example", "targetId": "wxid_example", "messageType": "text", "displayCategory": "text", "previewText": "已脱敏消息预览", "resource": { "kind": "", "status": "none" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Conversations" ], "description": "List normalized conversation messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/events": { "get": { "summary": "Pull protocol events by cursor", "operationId": "listAccountEvents", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Event page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "events", "cursor" ], "additionalProperties": false, "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ProtocolEvent" } }, "cursor": { "type": "string" } } } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "cursor": 42, "nextCursor": 42, "hasMore": false, "items": [ { "schemaVersion": "wechat.protocol.event.v1", "eventId": "evt_example", "eventType": "message.created", "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "runtimeShardId": "shard-a", "targetId": "wxid_example", "direction": "inbound", "msgType": 1, "messageType": "text", "previewText": "已脱敏消息预览", "cursor": "42", "source": "live", "aiEligible": true, "receivedAt": "2026-07-05T00:00:00.000Z", "resource": { "kind": "", "status": "none" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Pull protocol events by cursor. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/detail": { "post": { "summary": "Create or read Finder detail task/result", "operationId": "getFinderDetail", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Finder detail task or result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FinderDetailTask" } } }, "examples": { "default": { "value": { "data": { "taskId": "finder_example", "accountId": "wacct_example", "objectId": "finder_object_example", "status": "queued", "result": {}, "media": [ { "resourceId": "res_example", "resourceType": "finder_cover", "objectKey": "wechat/wacct_example/finder_cover.jpg", "status": "ready", "mimeType": "image/jpeg", "sizeBytes": 102400, "expiresAt": "2026-07-05T00:10:00.000Z" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Finder and SNS" ], "description": "Create or read Finder detail task/result. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderDetailRequest" }, "examples": { "default": { "value": { "objectId": "finder_object_id", "objectNonceId": "finder_object_nonce" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/detail-tasks/{taskId}": { "get": { "summary": "Get Finder detail task status", "operationId": "getFinderDetailTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/taskId" } ], "responses": { "200": { "description": "Finder detail task.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FinderDetailTask" } } }, "examples": { "default": { "value": { "data": { "taskId": "finder_example", "accountId": "wacct_example", "objectId": "finder_object_example", "status": "succeeded", "result": {}, "media": [ { "resourceId": "res_example", "resourceType": "finder_cover", "objectKey": "wechat/wacct_example/finder_cover.jpg", "status": "ready", "mimeType": "image/jpeg", "sizeBytes": 102400, "expiresAt": "2026-07-05T00:10:00.000Z" } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Finder and SNS" ], "description": "Get Finder detail task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/finder/search": { "post": { "summary": "Create Finder search task", "operationId": "createFinderSearchTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Finder search task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "finder_search_example", "type": "finder_search", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Finder and SNS" ], "description": "Create Finder search task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups": { "get": { "summary": "List groups from cloud event cache", "operationId": "listGroups", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Group list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatGroupPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "cursor": 42, "items": [ { "accountId": "wacct_example", "groupId": "room_example@chatroom", "targetId": "room_example@chatroom", "name": "客户群", "displayName": "客户群", "memberCount": 0, "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "source": "cloud_event_cache", "syncRequired": true } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "List groups from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}": { "get": { "summary": "Get group summary from cloud event cache", "operationId": "getGroup", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/groupId" } ], "responses": { "200": { "description": "Group summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatGroupResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "groupId": "room_example@chatroom", "targetId": "room_example@chatroom", "name": "客户群", "displayName": "客户群", "memberCount": 0, "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "source": "cloud_event_cache", "syncRequired": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Get group summary from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}/members": { "get": { "summary": "Read cached group members or protocol-required state", "operationId": "listGroupMembers", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/groupId" } ], "responses": { "200": { "description": "Group members cache state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequiredResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "groupId": "room_example@chatroom", "source": "cloud_task_queue_required", "syncRequired": true, "type": "group_members", "items": [], "note": "群成员需要由协议 worker 执行 groups/details 或群成员同步后回写。" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Read cached group members or protocol-required state. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/{groupId}/qrcode": { "get": { "summary": "Read cached group QR code state", "operationId": "getGroupQrcode", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/groupId" } ], "responses": { "200": { "description": "Group QR code cache state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequiredResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "groupId": "room_example@chatroom", "source": "cloud_task_queue_required", "syncRequired": true, "type": "group_qrcode", "qrcode": { "status": "not_cached", "expiresAt": "" }, "note": "群二维码需要由协议 worker 执行群二维码查询后回写，云端不会伪造二维码。" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Read cached group QR code state. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/details": { "post": { "summary": "Create group details task", "operationId": "createGroupDetailsTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Group details task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "groups_details_example", "type": "groups_details", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Create group details task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/search": { "get": { "summary": "Search groups from cloud event cache", "operationId": "searchGroups", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Group search result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatGroupPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "cursor": 42, "items": [ { "accountId": "wacct_example", "groupId": "room_example@chatroom", "targetId": "room_example@chatroom", "name": "客户群", "displayName": "客户群", "memberCount": 0, "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "source": "cloud_event_cache", "syncRequired": true } ], "query": "客户群" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Search groups from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/groups/sync": { "post": { "summary": "Create group sync task", "operationId": "createGroupSyncTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Group sync task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "groups_sync_example", "type": "groups_sync", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Groups" ], "description": "Create group sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/labels": { "get": { "summary": "List contact labels", "operationId": "listContactLabels", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Contact label list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatLabelPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "items": [], "note": "云端缓存暂未持久化联系人标签；调用 contacts/sync 后由协议 worker 回写。" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "List contact labels. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/{resourceId}": { "get": { "summary": "Get media resource status", "operationId": "getMediaResource", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/resourceId" } ], "responses": { "200": { "description": "Media resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MediaResource" } } }, "examples": { "default": { "value": { "data": { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "available", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Get media resource status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/{resourceId}/sign": { "post": { "summary": "Sign short-lived media URL", "operationId": "signMediaResource", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/resourceId" } ], "responses": { "200": { "description": "Signed media resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MediaResource" } } }, "examples": { "default": { "value": { "data": { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "available", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "signedUrl": "https://cos.example.invalid/signed/media-resource" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Sign short-lived media URL. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyJsonRequest" }, "examples": { "default": { "value": {} } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/resolve": { "post": { "summary": "Register and resolve a WeChat media resource", "operationId": "resolveMediaResource", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Media resource record.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MediaResource" } } }, "examples": { "default": { "value": { "data": { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "pending", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Register and resolve a WeChat media resource. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaResourceRequest" }, "examples": { "default": { "value": { "type": "image", "mimeType": "image/jpeg", "sizeBytes": 102400, "fileName": "image.jpg" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/resources/sign": { "post": { "summary": "Sign short-lived media URLs in batch", "operationId": "signMediaResources", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Signed media resource list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MediaResource" } } } } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "items": [ { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "available", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "signedUrl": "https://cos.example.invalid/signed/media-resource" } ], "failed": [], "expiresAt": "2026-07-05T00:10:00.000Z", "source": "cloud_object_storage_signer" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Sign short-lived media URLs in batch. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaResourceBatchSignRequest" }, "examples": { "default": { "value": { "resourceIds": [ "res_example" ] } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/media/uploads": { "post": { "summary": "Create upload resource for outbound media", "operationId": "createMediaUpload", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Upload resource record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaResourceResponse" }, "examples": { "default": { "value": { "data": { "resourceId": "res_example", "accountId": "wacct_example", "type": "upload_asset", "status": "pending", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Create upload resource for outbound media. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaResourceRequest" }, "examples": { "default": { "value": { "type": "image", "mimeType": "image/jpeg", "sizeBytes": 102400, "fileName": "image.jpg" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/history-sync": { "post": { "summary": "Create message history sync task", "operationId": "createMessageHistorySyncTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Message history sync task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "history_sync_example", "type": "history_sync", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Messaging" ], "description": "Create message history sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/normalize": { "post": { "summary": "Normalize cached protocol messages", "operationId": "normalizeMessages", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Normalized messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedMessage" } } } } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "targetId": "wxid_example", "source": "cloud_event_cache", "syncRequired": true, "schemaVersion": "wechat.protocol.normalized-messages.v1", "cursor": 42, "nextCursor": 42, "hasMore": false, "items": [ { "eventId": "evt_example", "targetId": "wxid_example", "messageType": "text", "displayCategory": "text", "previewText": "已脱敏消息预览", "resource": { "kind": "", "status": "none" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "requestBody": { "required": true, "description": "Message normalization request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizeMessagesRequest" } } } }, "tags": [ "Personal WeChat Messaging" ], "description": "Normalize cached protocol messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/sync": { "post": { "summary": "Create message sync task", "operationId": "createMessageSyncTask", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Message sync task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "message_sync_example", "type": "message_sync", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Messaging" ], "description": "Create message sync task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/text": { "post": { "summary": "Create text send task", "operationId": "createTextSendTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/idempotencyKey" }, { "$ref": "#/components/parameters/traceId" } ], "responses": { "200": { "description": "Send task.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendTask" } } }, "examples": { "default": { "value": { "data": { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "queued", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Creates a text send task. Body supports targetId, content/text, clientActionId, proposalId, sourceMessageId, and traceId.", "requestBody": { "required": true, "description": "Text send request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSendRequest" } } } }, "tags": [ "Personal WeChat Messaging" ] } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/messages/types": { "get": { "summary": "Get normalized message type catalog", "operationId": "getMessageTypes", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Message type catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatMessageTypeCatalogResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "schemaVersion": "wechat.protocol.message-types.v1", "messageTypes": [ "text", "image", "voice", "video", "unknown" ], "conversationTypes": [ "contact", "group", "official", "system" ], "displayCategories": [ "text", "media", "link", "app", "system", "payment", "unknown" ], "resourceStatuses": [ "none", "pending", "ready", "failed" ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Messaging" ], "description": "Get normalized message type catalog. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts": { "get": { "summary": "List official accounts from cloud event cache", "operationId": "listOfficialAccounts", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Official account list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatOfficialAccountPageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "items": [ { "officialId": "gh_example", "name": "示例公众号", "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "unreadCount": 0 } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Official Accounts" ], "description": "List official accounts from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts/{officialId}/messages": { "get": { "summary": "List official account messages", "operationId": "listOfficialAccountMessages", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/officialId" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Official account messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatMessagePageResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "targetId": "gh_example", "conversationType": "official", "source": "cloud_event_cache", "syncRequired": true, "schemaVersion": "wechat.protocol.normalized-messages.v1", "cursor": 42, "nextCursor": 42, "hasMore": false, "items": [ { "eventId": "evt_example", "targetId": "wxid_example", "messageType": "text", "displayCategory": "text", "previewText": "已脱敏消息预览", "resource": { "kind": "", "status": "none" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Official Accounts" ], "description": "List official account messages. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/official-accounts/hub": { "get": { "summary": "Get official account hub summary", "operationId": "getOfficialAccountHub", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Official account hub.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatOfficialHubResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "totalCount": 1, "unreadCount": 0, "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "items": [ { "officialId": "gh_example", "name": "示例公众号", "latest": { "previewText": "已脱敏消息预览", "messageType": "text", "updatedAt": "2026-07-05T00:00:00.000Z", "createdAt": "2026-07-05T00:00:00.000Z" }, "unreadCount": 0 } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Official Accounts" ], "description": "Get official account hub summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/online-status": { "get": { "summary": "Get account online status", "operationId": "getAccountOnlineStatus", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Account online status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeSummary" } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "online", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "online", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Get account online status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/profile": { "get": { "summary": "Get cloud account profile summary", "operationId": "getAccountProfile", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Cloud account profile summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatProfileResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "displayName": "客服微信一号", "avatarUrl": "", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "protocolDeviceType": "ipad", "hostDeviceId": "macbook-pro-local", "mode": "cloud", "source": "cloud_runtime_summary", "syncRequired": true, "runtime": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "online", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "online", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" }, "latestEventAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Get cloud account profile summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/recipients/resolve": { "get": { "summary": "Resolve one recipient from cloud event cache", "operationId": "resolveRecipient", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Recipient candidates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatRecipientResolveResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "items": [ { "query": "张三", "matches": [ { "targetId": "wxid_example", "displayName": "张三", "conversationType": "contact", "confidence": 1 } ] } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Resolve one recipient from cloud event cache. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." }, "post": { "summary": "Resolve recipient candidates in batch", "operationId": "resolveRecipients", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Recipient candidates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatRecipientResolveResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "source": "cloud_event_cache", "syncRequired": true, "items": [ { "query": "张三", "matches": [ { "targetId": "wxid_example", "displayName": "张三", "conversationType": "contact", "confidence": 1 } ] } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Contacts" ], "description": "Resolve recipient candidates in batch. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientResolveRequest" }, "examples": { "default": { "value": { "queries": [ "张三", "客户群" ] } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/recover": { "post": { "summary": "Request protocol runtime recovery", "operationId": "recoverAccount", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Runtime state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeSummaryResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "recovering", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "recovering", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Request protocol runtime recovery. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoverRequest" }, "examples": { "default": { "value": { "reason": "manual-recover" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/runtime-summary": { "get": { "summary": "Get account runtime summary", "operationId": "getAccountRuntimeSummary", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Account runtime summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeSummary" } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "online", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "online", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Get account runtime summary. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/scopes": { "get": { "summary": "Get account scopes", "operationId": "getAccountScopes", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Account scope directory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalWechatScopeDirectoryResponse" }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "scopes": [ { "scope": "messages.send", "capability": "action.execute", "description": "创建受控发送任务。", "enabled": true } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Accounts" ], "description": "Get account scopes. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/send-tasks/{taskId}": { "get": { "summary": "Get text send task status", "operationId": "getSendTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/taskId" } ], "responses": { "200": { "description": "Send task.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SendTask" } } }, "examples": { "default": { "value": { "data": { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "sent", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Messaging" ], "description": "Get text send task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/sns/timeline": { "get": { "summary": "Create SNS timeline query task", "operationId": "createSnsTimelineTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "SNS timeline task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "sns_timeline_example", "type": "sns_timeline", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Finder and SNS" ], "description": "Create SNS timeline query task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/sns/user-page": { "get": { "summary": "Create SNS user page query task", "operationId": "createSnsUserPageTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/userName" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "SNS user page task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskResponse" }, "examples": { "default": { "value": { "data": { "taskId": "sns_user_page_example", "type": "sns_user_page", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Finder and SNS" ], "description": "Create SNS user page query task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolGenericTaskRequest" }, "examples": { "default": { "value": { "query": "客户昵称", "limit": 50, "reason": "manual-sync" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}": { "get": { "summary": "Get unified task status", "operationId": "getTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/taskId" } ], "responses": { "200": { "description": "Unified task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedProtocolTaskResponse" }, "examples": { "default": { "value": { "data": { "taskType": "send", "taskId": "send_example", "accountId": "wacct_example", "status": "succeeded", "rawStatus": "succeeded", "targetId": "wxid_example", "messageType": "text", "clientActionId": "act_example", "proposalId": "", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "2026-07-05T00:00:01.000Z", "data": { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "sent", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Tasks" ], "description": "Get unified task status. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}/cancel": { "post": { "summary": "Cancel a pending task", "operationId": "cancelTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/taskId" } ], "responses": { "200": { "description": "Cancelled task status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedProtocolTaskResponse" }, "examples": { "default": { "value": { "data": { "taskType": "send", "taskId": "send_example", "accountId": "wacct_example", "status": "cancelled", "rawStatus": "cancelled", "targetId": "wxid_example", "messageType": "text", "clientActionId": "act_example", "proposalId": "", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "2026-07-05T00:00:01.000Z", "data": { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "cancelled", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Tasks" ], "description": "Cancel a pending task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskMutationRequest" }, "examples": { "default": { "value": { "reason": "manual-operation" } } } } } } } }, "/api/capabilities/personal-wechat/v1/accounts/{accountId}/tasks/{taskId}/retry": { "post": { "summary": "Retry a failed or cancelled task", "operationId": "retryTask", "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/taskId" } ], "responses": { "200": { "description": "Retried task status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedProtocolTaskResponse" }, "examples": { "default": { "value": { "data": { "taskType": "send", "taskId": "send_example", "accountId": "wacct_example", "status": "queued", "rawStatus": "queued", "targetId": "wxid_example", "messageType": "text", "clientActionId": "act_example", "proposalId": "", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "2026-07-05T00:00:01.000Z", "data": { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "queued", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Tasks" ], "description": "Retry a failed or cancelled task. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskMutationRequest" }, "examples": { "default": { "value": { "reason": "manual-operation" } } } } } } } }, "/api/capabilities/personal-wechat/v1/storage/entitlement": { "get": { "summary": "Get object storage entitlement", "operationId": "getStorageEntitlement", "responses": { "200": { "description": "Object storage entitlement.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StorageEntitlement" } } }, "examples": { "default": { "value": { "data": { "objectStorageEnabled": true, "storageQuotaBytes": 1073741824, "storageUsedBytes": 1024, "storageRetentionDays": 30, "maxFileSizeBytes": 104857600, "monthlyEgressQuotaBytes": 1073741824 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Personal WeChat Media" ], "description": "Get object storage entitlement. Public personal WeChat capability endpoint. It uses product-level identifiers where applicable, bearer-token authorization, and redacted responses so callers do not handle raw WeChat protocol secrets." } }, "/api/protocol/accounts/{accountId}/health": { "post": { "summary": "Worker updates account health", "operationId": "updateProtocolHealth", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "security": [ { "protocolWorkerKey": [] } ], "responses": { "200": { "description": "Runtime state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RuntimeSummary" } } }, "examples": { "default": { "value": { "data": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "online", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "online", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-internal": true, "tags": [ "Protocol Workers" ], "description": "Worker updates account health. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolHealthUpdateRequest" }, "examples": { "default": { "value": { "status": "online", "workerId": "worker-mac-1", "queueLagMs": 0 } } } } } } } }, "/api/protocol/accounts/{accountId}/media/resource-results": { "post": { "summary": "Worker writes media resource result", "operationId": "writeMediaResourceResult", "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "security": [ { "protocolWorkerKey": [] } ], "responses": { "200": { "description": "Media resource.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MediaResource" } } }, "examples": { "default": { "value": { "data": { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "available", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-internal": true, "tags": [ "Protocol Workers" ], "description": "Worker writes media resource result. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolMediaResourceResultRequest" }, "examples": { "default": { "value": { "resourceId": "res_example", "status": "available", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "objectKey": "wechat/account/resource.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400 } } } } } } } } }, "/api/protocol/workers/claim": { "post": { "summary": "Worker claims assignments and tasks", "operationId": "claimProtocolWorker", "security": [ { "protocolWorkerKey": [] } ], "responses": { "200": { "description": "Worker assignments.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "required": [ "worker", "assignments" ], "additionalProperties": true, "properties": { "worker": { "type": "object", "additionalProperties": true }, "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/ProtocolWorkerAssignment" } } } } } }, "examples": { "default": { "value": { "data": { "assignments": [ { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "protocolDeviceType": "ipad", "hostDeviceId": "macbook-pro-local", "sendTasks": [ { "taskId": "send_example", "accountId": "wacct_example", "targetId": "wxid_example", "messageType": "text", "status": "queued", "clientActionId": "act_example", "proposalId": "", "dedupeKey": "act_example", "workerId": "worker-mac-1", "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } ], "finderDetailTasks": [ { "taskId": "finder_example", "accountId": "wacct_example", "objectId": "finder_object_example", "status": "queued", "result": {}, "media": [ { "resourceId": "res_example", "resourceType": "finder_cover", "objectKey": "wechat/wacct_example/finder_cover.jpg", "status": "ready", "mimeType": "image/jpeg", "sizeBytes": 102400, "expiresAt": "2026-07-05T00:10:00.000Z" } ] } ], "genericTasks": [ { "taskId": "contacts_sync_example", "type": "contacts_sync", "accountId": "wacct_example", "status": "queued", "params": { "query": "示例查询", "ids": [], "limit": 50 }, "errorCode": "", "errorMessage": "", "createdAt": "2026-07-05T00:00:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z", "completedAt": "", "source": "cloud_task_queue" } ], "mediaResources": [ { "resourceId": "res_example", "accountId": "wacct_example", "type": "image", "status": "pending", "mimeType": "image/jpeg", "sizeBytes": 102400, "objectStorage": { "provider": "cos", "bucket": "wechat-media-example", "region": "ap-guangzhou", "objectKey": "wechat/wacct_example/res_example.jpg", "mimeType": "image/jpeg", "sizeBytes": 102400, "checksum": "sha256-example" }, "errorCode": "", "errorMessage": "", "expiresAt": "2026-07-05T00:10:00.000Z", "updatedAt": "2026-07-05T00:00:00.000Z" } ], "localTaskPath": "/api/wechat-bind-sessions/bind_example/local-task", "health": { "accountId": "wacct_example", "internalInstanceId": "wxinst_example", "bindSessionId": "bind_example", "cloudKeyId": "key_slot_example", "hostDeviceId": "macbook-pro-local", "protocolDeviceType": "ipad", "protocolDeviceProfileVersion": "v1", "status": "online", "bindStatus": "bound", "workerId": "worker-mac-1", "workerLeaseExpiresAt": "2026-07-05T00:10:00.000Z", "health": { "status": "online", "workerId": "worker-mac-1" }, "recover": {}, "updatedAt": "2026-07-05T00:00:00.000Z" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-internal": true, "requestBody": { "required": true, "description": "Worker claim request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtocolWorkerClaimRequest" } } } }, "tags": [ "Protocol Workers" ], "description": "Worker claims assignments and tasks. Internal protocol worker endpoint for claim, health, or result writeback. It is marked x-internal, uses the protocol worker key, and is not part of the public capability SDK." } }, "/health": { "get": { "summary": "Cloud API health check", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Health status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "examples": { "default": { "value": { "ok": true, "service": "wechat-cloud-api", "updatedAt": "2026-07-05T00:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "tags": [ "Health" ], "description": "Cloud API health check. Public health probe for deployment readiness and load balancer checks. It returns only service status metadata and no tenant, account, or protocol data." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "protocolWorkerKey": { "type": "apiKey", "in": "header", "name": "X-Protocol-Worker-Key" } }, "parameters": { "accountId": { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product-level WeChat account ID. Access is limited by the caller token." }, "resourceId": { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media resource ID." }, "taskId": { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unified task ID." }, "targetId": { "name": "targetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation target ID." }, "officialId": { "name": "officialId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Official account ID." }, "groupId": { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Group chat ID." }, "idempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional idempotency key for write actions. SDKs may generate it automatically." }, "traceId": { "name": "X-Trace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional trace ID for API, worker, and audit correlation." }, "query": { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text. The API also accepts q as a compatibility alias.", "example": "张三" }, "limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "description": "Maximum number of cached records or tasks to return.", "example": 50 }, "cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cloud event cursor or page cursor.", "example": "0" }, "since": { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compatibility alias for cursor.", "example": "0" }, "userName": { "name": "userName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Contact username or wxid surrogate for SNS user-page tasks.", "example": "wxid_xxx" } }, "schemas": { "ApiError": { "type": "object", "required": [ "error", "message" ], "additionalProperties": false, "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } }, "HealthResponse": { "type": "object", "required": [ "ok", "service", "updatedAt" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PersonalWechatAccount": { "type": "object", "required": [ "accountId", "status" ], "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "internalInstanceId": { "type": "string" }, "bindSessionId": { "type": "string" }, "cloudKeyId": { "type": "string" }, "protocolDeviceType": { "type": "string", "enum": [ "ipad", "mac", "win", "harmony", "car", "watch" ] }, "status": { "type": "string" }, "online": { "type": "boolean" }, "nickname": { "type": "string" }, "avatarUrl": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RuntimeSummary": { "type": "object", "required": [ "accountId", "status", "online" ], "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "internalInstanceId": { "type": "string" }, "bindSessionId": { "type": "string" }, "cloudKeyId": { "type": "string" }, "protocolDeviceType": { "type": "string" }, "runtimeShardId": { "type": "string" }, "status": { "type": "string" }, "online": { "type": "boolean" }, "lastSeenAt": { "type": "string", "format": "date-time" }, "recoverRequestedAt": { "type": "string", "format": "date-time" } } }, "ProtocolEvent": { "type": "object", "required": [ "schemaVersion", "eventId", "eventType", "accountId", "targetId", "messageType", "cursor" ], "additionalProperties": false, "properties": { "schemaVersion": { "type": "string", "enum": [ "wechat.protocol.event.v1" ] }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "accountId": { "type": "string" }, "internalInstanceId": { "type": "string" }, "bindSessionId": { "type": "string" }, "cloudKeyId": { "type": "string" }, "runtimeShardId": { "type": "string" }, "targetId": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "unknown" ] }, "msgType": { "type": "integer" }, "messageType": { "type": "string" }, "previewText": { "type": "string", "description": "Redacted display preview. Raw chat body is not accepted as API input." }, "cursor": { "type": "string" }, "source": { "type": "string" }, "aiEligible": { "type": "boolean" }, "receivedAt": { "type": "string", "format": "date-time" }, "resource": { "$ref": "#/components/schemas/MediaResourceRef" } } }, "TextSendRequest": { "type": "object", "required": [ "targetId" ], "additionalProperties": false, "properties": { "targetId": { "type": "string" }, "content": { "type": "string", "maxLength": 4000, "description": "Text to send. This is accepted only by the send task creation API." }, "text": { "type": "string", "maxLength": 4000, "deprecated": true }, "atWxIDList": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }, "clientActionId": { "type": "string" }, "proposalId": { "type": "string" }, "sourceMessageId": { "type": "string" }, "traceId": { "type": "string" } } }, "SendTask": { "type": "object", "required": [ "taskId", "accountId", "targetId", "status" ], "additionalProperties": false, "properties": { "taskId": { "type": "string" }, "accountId": { "type": "string" }, "targetId": { "type": "string" }, "messageType": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "leased", "sending", "sent", "delivered", "failed", "cancelled" ] }, "clientActionId": { "type": "string" }, "proposalId": { "type": "string" }, "dedupeKey": { "type": "string" }, "workerId": { "type": "string" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "NormalizeMessagesRequest": { "type": "object", "required": [ "eventRefs" ], "additionalProperties": false, "properties": { "eventRefs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 200 }, "cursor": { "type": "string" } }, "description": "Only accepts event references from cloud cache. Raw message body, XML, chat content, and contact detail fields are rejected." }, "NormalizedMessage": { "type": "object", "required": [ "eventId", "messageType", "targetId" ], "additionalProperties": false, "properties": { "eventId": { "type": "string" }, "targetId": { "type": "string" }, "messageType": { "type": "string" }, "displayCategory": { "type": "string" }, "previewText": { "type": "string" }, "resource": { "$ref": "#/components/schemas/MediaResourceRef" } } }, "MediaResourceRef": { "type": "object", "additionalProperties": false, "properties": { "resourceId": { "type": "string" }, "resourceType": { "type": "string" }, "objectKey": { "type": "string", "description": "COS object key scoped by tenantId/userId/accountId." }, "status": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "MediaResource": { "type": "object", "required": [ "resourceId", "accountId", "status" ], "additionalProperties": false, "properties": { "resourceId": { "type": "string" }, "accountId": { "type": "string" }, "resourceType": { "type": "string" }, "status": { "type": "string" }, "objectKey": { "type": "string" }, "signedUrl": { "type": "string", "description": "Short-lived URL only; never includes urlToken/decodeKey." }, "expiresAt": { "type": "string", "format": "date-time" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" } } }, "FinderDetailTask": { "type": "object", "required": [ "taskId", "accountId", "objectId", "status" ], "additionalProperties": false, "properties": { "taskId": { "type": "string" }, "accountId": { "type": "string" }, "objectId": { "type": "string" }, "status": { "type": "string" }, "result": { "type": "object", "additionalProperties": true }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaResourceRef" } } } }, "StorageEntitlement": { "type": "object", "required": [ "objectStorageEnabled", "storageQuotaBytes", "storageUsedBytes" ], "additionalProperties": false, "properties": { "objectStorageEnabled": { "type": "boolean" }, "storageQuotaBytes": { "type": "integer" }, "storageUsedBytes": { "type": "integer" }, "storageRetentionDays": { "type": "integer" }, "maxFileSizeBytes": { "type": "integer" }, "monthlyEgressQuotaBytes": { "type": "integer" } } }, "ProtocolWorkerClaimRequest": { "type": "object", "required": [ "workerId" ], "additionalProperties": false, "properties": { "workerId": { "type": "string" }, "runtimeShardId": { "type": "string" }, "hostDeviceId": { "type": "string" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 200 }, "version": { "type": "string" } } }, "ProtocolWorkerAssignment": { "type": "object", "required": [ "accountId" ], "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "internalInstanceId": { "type": "string" }, "bindSessionId": { "type": "string" }, "cloudKeyId": { "type": "string" }, "sendTasks": { "type": "array", "items": { "$ref": "#/components/schemas/SendTask" } }, "finderDetailTasks": { "type": "array", "items": { "$ref": "#/components/schemas/FinderDetailTask" } }, "protocolDeviceType": { "type": "string" }, "hostDeviceId": { "type": "string" }, "localTaskPath": { "type": "string" }, "health": { "$ref": "#/components/schemas/RuntimeSummary" }, "genericTasks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mediaResources": { "type": "array", "items": { "$ref": "#/components/schemas/MediaResource" } } } }, "DataEnvelope": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": true } } }, "LatestPreview": { "type": "object", "required": [ "previewText", "messageType", "updatedAt" ], "additionalProperties": false, "properties": { "previewText": { "type": "string", "description": "Redacted display preview." }, "messageType": { "type": "string", "description": "Normalized message type." }, "updatedAt": { "type": "string", "description": "Latest cached update time." }, "createdAt": { "type": "string", "description": "Latest cached create time." } } }, "PersonalWechatContact": { "type": "object", "required": [ "accountId", "contactId", "targetId", "nickname", "source", "syncRequired" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "contactId": { "type": "string", "description": "Product-level contact ID." }, "targetId": { "type": "string", "description": "Conversation target ID." }, "userName": { "type": "string", "description": "Protocol username or wxid surrogate after redaction." }, "nickname": { "type": "string", "description": "Display nickname." }, "remarkName": { "type": "string", "description": "Remark name when available." }, "alias": { "type": "string", "description": "Alias when available." }, "avatarUrl": { "type": "string", "description": "Avatar URL when available." }, "latest": { "$ref": "#/components/schemas/LatestPreview" }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." } } }, "PersonalWechatContactPage": { "type": "object", "required": [ "accountId", "source", "syncRequired", "cursor", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "cursor": { "type": "integer", "description": "Current cloud event cursor." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatContact" } }, "query": { "type": "string", "description": "Search query when this page is produced by a search endpoint." } } }, "PersonalWechatLabel": { "type": "object", "required": [ "labelId", "name" ], "additionalProperties": false, "properties": { "labelId": { "type": "string", "description": "Label ID." }, "name": { "type": "string", "description": "Label name." }, "count": { "type": "integer", "description": "Cached contact count." } } }, "PersonalWechatLabelPage": { "type": "object", "required": [ "accountId", "source", "syncRequired", "cursor", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "cursor": { "type": "integer", "description": "Current cloud event cursor." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatLabel" } }, "note": { "type": "string", "description": "Human-readable cache or sync note." } } }, "PersonalWechatGroup": { "type": "object", "required": [ "accountId", "groupId", "targetId", "displayName", "source", "syncRequired" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "groupId": { "type": "string", "description": "Group chat ID." }, "targetId": { "type": "string", "description": "Conversation target ID." }, "name": { "type": "string", "description": "Group name." }, "displayName": { "type": "string", "description": "Display group name." }, "memberCount": { "type": "integer", "description": "Cached member count." }, "latest": { "$ref": "#/components/schemas/LatestPreview" }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." } } }, "PersonalWechatGroupPage": { "type": "object", "required": [ "accountId", "source", "syncRequired", "cursor", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "cursor": { "type": "integer", "description": "Current cloud event cursor." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatGroup" } }, "query": { "type": "string", "description": "Search query when this page is produced by a search endpoint." } } }, "PersonalWechatGroupProtocolRequired": { "type": "object", "required": [ "accountId", "groupId", "source", "syncRequired", "type", "note" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "groupId": { "type": "string", "description": "Group chat ID." }, "source": { "type": "string", "description": "Data source, normally cloud_task_queue_required." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol worker task is required." }, "type": { "type": "string", "description": "Required protocol query type." }, "items": { "type": "array", "description": "Cached group members. Empty until worker writeback.", "items": { "type": "object", "required": [], "additionalProperties": true, "properties": {} } }, "qrcode": { "type": "object", "required": [ "status", "expiresAt" ], "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Cached QR code status." }, "expiresAt": { "type": "string", "description": "QR code expiry time if cached." } } }, "note": { "type": "string", "description": "Human-readable sync requirement note." } } }, "PersonalWechatConversation": { "type": "object", "required": [ "targetId", "displayName", "conversationType", "messageType", "previewText", "lastCursor", "updatedAt" ], "additionalProperties": false, "properties": { "targetId": { "type": "string", "description": "Conversation target ID." }, "displayName": { "type": "string", "description": "Display name inferred from cached events." }, "conversationType": { "type": "string", "description": "contact, group, official, or system." }, "messageType": { "type": "string", "description": "Latest normalized message type." }, "previewText": { "type": "string", "description": "Redacted latest message preview." }, "lastCursor": { "type": "integer", "description": "Latest protocol event cursor for this conversation." }, "updatedAt": { "type": "string", "description": "Latest event time." }, "unreadCount": { "type": "integer", "description": "Cached unread count." } } }, "PersonalWechatConversationPage": { "type": "object", "required": [ "accountId", "source", "syncRequired", "cursor", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "cursor": { "type": "integer", "description": "Current cloud event cursor." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatConversation" } } } }, "PersonalWechatMessagePage": { "type": "object", "required": [ "accountId", "targetId", "conversationType", "source", "syncRequired", "cursor", "nextCursor", "hasMore", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "targetId": { "type": "string", "description": "Conversation target ID." }, "conversationType": { "type": "string", "description": "contact, group, official, or system." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "schemaVersion": { "type": "string", "description": "Normalized message schema version." }, "cursor": { "type": "integer", "description": "Current cloud event cursor." }, "nextCursor": { "type": "integer", "description": "Cursor to use for the next page." }, "hasMore": { "type": "boolean", "description": "Whether more events are likely available." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NormalizedMessage" } } } }, "PersonalWechatOfficialAccount": { "type": "object", "required": [ "officialId", "name", "latest", "unreadCount" ], "additionalProperties": false, "properties": { "officialId": { "type": "string", "description": "Official account ID." }, "name": { "type": "string", "description": "Official account display name." }, "latest": { "$ref": "#/components/schemas/LatestPreview" }, "unreadCount": { "type": "integer", "description": "Cached unread count." } } }, "PersonalWechatOfficialAccountPage": { "type": "object", "required": [ "accountId", "source", "syncRequired", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatOfficialAccount" } } } }, "PersonalWechatOfficialHub": { "type": "object", "required": [ "accountId", "source", "syncRequired", "totalCount", "unreadCount", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "totalCount": { "type": "integer", "description": "Official account count." }, "unreadCount": { "type": "integer", "description": "Cached unread count." }, "latest": { "$ref": "#/components/schemas/LatestPreview" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatOfficialAccount" } } } }, "PersonalWechatRecipientCandidate": { "type": "object", "required": [ "targetId", "displayName", "conversationType", "confidence" ], "additionalProperties": false, "properties": { "targetId": { "type": "string", "description": "Resolved target ID." }, "displayName": { "type": "string", "description": "Resolved display name." }, "conversationType": { "type": "string", "description": "contact, group, official, or system." }, "confidence": { "type": "number", "description": "Heuristic match confidence." } } }, "PersonalWechatRecipientResolution": { "type": "object", "required": [ "query", "matches" ], "additionalProperties": false, "properties": { "query": { "type": "string", "description": "Original query string." }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatRecipientCandidate" } } } }, "PersonalWechatRecipientResolveResult": { "type": "object", "required": [ "accountId", "source", "syncRequired", "items" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "source": { "type": "string", "description": "Data source, normally cloud_event_cache." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatRecipientResolution" } } } }, "ProtocolGenericTaskParams": { "type": "object", "required": [ "ids", "limit" ], "additionalProperties": false, "properties": { "sinceCursor": { "type": "string", "description": "Cursor used for sync-like protocol tasks." }, "targetId": { "type": "string", "description": "Target conversation ID." }, "groupId": { "type": "string", "description": "Group chat ID." }, "userName": { "type": "string", "description": "Contact username or wxid surrogate." }, "query": { "type": "string", "description": "Search query." }, "ids": { "type": "array", "description": "Explicit target IDs.", "items": { "type": "string" } }, "limit": { "type": "integer", "description": "Requested result limit." }, "reason": { "type": "string", "description": "Redacted request reason." } } }, "ProtocolGenericTask": { "type": "object", "required": [ "taskId", "type", "accountId", "status", "params", "createdAt", "updatedAt", "source" ], "additionalProperties": false, "properties": { "taskId": { "type": "string", "description": "Protocol task ID." }, "type": { "type": "string", "description": "Generic task type." }, "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "status": { "type": "string", "description": "queued, processing, succeeded, failed, or cancelled." }, "params": { "$ref": "#/components/schemas/ProtocolGenericTaskParams" }, "errorCode": { "type": "string", "description": "Failure code when available." }, "errorMessage": { "type": "string", "description": "Redacted failure message when available." }, "createdAt": { "type": "string", "description": "Creation time." }, "updatedAt": { "type": "string", "description": "Update time." }, "completedAt": { "type": "string", "description": "Completion time when available." }, "source": { "type": "string", "description": "Data source, normally cloud_task_queue." } } }, "UnifiedProtocolTask": { "type": "object", "required": [ "taskType", "taskId", "accountId", "status", "rawStatus", "createdAt", "updatedAt", "data" ], "additionalProperties": false, "properties": { "taskType": { "type": "string", "description": "Unified task type." }, "taskId": { "type": "string", "description": "Task ID." }, "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "status": { "type": "string", "description": "Unified status." }, "rawStatus": { "type": "string", "description": "Underlying task status." }, "targetId": { "type": "string", "description": "Target conversation ID for send tasks." }, "messageType": { "type": "string", "description": "Message type for send tasks." }, "resourceId": { "type": "string", "description": "Media resource ID for media tasks." }, "resourceType": { "type": "string", "description": "Media resource type for media tasks." }, "objectId": { "type": "string", "description": "Finder object ID for Finder tasks." }, "objectNonceId": { "type": "string", "description": "Finder object nonce ID when available." }, "finderUsername": { "type": "string", "description": "Finder username when available." }, "clientActionId": { "type": "string", "description": "Client action ID for write tasks." }, "proposalId": { "type": "string", "description": "Proposal ID when a human/agent proposal exists." }, "errorCode": { "type": "string", "description": "Failure code when available." }, "errorMessage": { "type": "string", "description": "Redacted failure message when available." }, "createdAt": { "type": "string", "description": "Creation time." }, "updatedAt": { "type": "string", "description": "Update time." }, "completedAt": { "type": "string", "description": "Completion time when available." }, "data": { "type": "object", "required": [], "additionalProperties": true, "properties": {} } } }, "PersonalWechatBindSession": { "type": "object", "required": [ "bindSessionId", "accountId", "internalInstanceId", "cloudKeyId", "protocolDeviceType", "status", "createdAt" ], "additionalProperties": false, "properties": { "bindSessionId": { "type": "string", "description": "Cloud bind session ID." }, "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "internalInstanceId": { "type": "string", "description": "Internal protocol runtime ID." }, "hostDeviceId": { "type": "string", "description": "Host device ID." }, "cloudKeyId": { "type": "string", "description": "Cloud key slot ID, not the raw WeChat key." }, "wechatKeyId": { "type": "string", "description": "Key slot ID kept for backward compatibility, not the raw WeChat key." }, "protocolDeviceType": { "type": "string", "description": "Protocol device profile type." }, "protocolDeviceProfileVersion": { "type": "string", "description": "Protocol device profile version." }, "allowedProtocolDeviceTypes": { "type": "array", "description": "Allowed protocol device profile types.", "items": { "type": "string" } }, "defaultProtocolDeviceType": { "type": "string", "description": "Default protocol device profile type." }, "allowProtocolDeviceSwitch": { "type": "boolean", "description": "Whether the caller may switch protocol device profile." }, "seatIndex": { "type": "integer", "description": "Wechat seat index." }, "seatId": { "type": "string", "description": "Wechat seat ID." }, "proxyRequired": { "type": "boolean", "description": "Whether proxy is required." }, "proxyBypassed": { "type": "boolean", "description": "Whether proxy was bypassed." }, "proxyLease": { "type": "object", "required": [], "additionalProperties": true, "properties": {} }, "entitlement": { "type": "object", "required": [], "additionalProperties": true, "properties": {} }, "status": { "type": "string", "description": "Bind session status." }, "lastEvent": { "type": "string", "description": "Latest bind session event." }, "createdAt": { "type": "string", "description": "Creation time." }, "updatedAt": { "type": "string", "description": "Update time." } } }, "PersonalWechatProfile": { "type": "object", "required": [ "accountId", "displayName", "mode", "source", "syncRequired", "runtime" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "displayName": { "type": "string", "description": "Account display name." }, "avatarUrl": { "type": "string", "description": "Avatar URL when available." }, "bindSessionId": { "type": "string", "description": "Cloud bind session ID." }, "cloudKeyId": { "type": "string", "description": "Cloud key slot ID, not the raw WeChat key." }, "protocolDeviceType": { "type": "string", "description": "Protocol device profile type." }, "hostDeviceId": { "type": "string", "description": "Host device ID." }, "mode": { "type": "string", "description": "Runtime mode." }, "source": { "type": "string", "description": "Profile data source." }, "syncRequired": { "type": "boolean", "description": "Whether a protocol sync task is still required for fresher data." }, "runtime": { "type": "object", "required": [], "additionalProperties": true, "properties": {} }, "latestEventAt": { "type": "string", "description": "Latest cached event time." } } }, "PersonalWechatCapabilityDirectory": { "type": "object", "required": [ "accountId", "mode", "available", "unavailable", "runtime", "storage", "notes" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "mode": { "type": "string", "description": "Runtime mode." }, "available": { "type": "array", "description": "Available capability codes.", "items": { "type": "string" } }, "unavailable": { "type": "array", "description": "Unavailable capability codes.", "items": { "type": "string" } }, "runtime": { "type": "object", "required": [ "status", "health", "workerId" ], "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Runtime availability status." }, "health": { "type": "string", "description": "Worker health status." }, "workerId": { "type": "string", "description": "Worker ID when available." } } }, "storage": { "type": "object", "required": [ "objectStorageEnabled", "storageAvailableBytes", "maxFileSizeBytes" ], "additionalProperties": false, "properties": { "objectStorageEnabled": { "type": "boolean", "description": "Whether object storage is enabled." }, "storageAvailableBytes": { "type": "integer", "description": "Remaining storage quota." }, "maxFileSizeBytes": { "type": "integer", "description": "Maximum upload size." } } }, "notes": { "type": "array", "description": "Human-readable boundary notes.", "items": { "type": "string" } } } }, "PersonalWechatScopeItem": { "type": "object", "required": [ "scope", "capability", "description", "enabled" ], "additionalProperties": false, "properties": { "scope": { "type": "string", "description": "OAuth-like public scope name." }, "capability": { "type": "string", "description": "Internal capability code." }, "description": { "type": "string", "description": "Human-readable scope description." }, "enabled": { "type": "boolean", "description": "Whether this scope is currently enabled." } } }, "PersonalWechatScopeDirectory": { "type": "object", "required": [ "accountId", "scopes" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalWechatScopeItem" } } } }, "PersonalWechatActionValidation": { "type": "object", "required": [ "accountId", "action", "targetId", "allowed", "requiredCapability", "riskLevel", "requiresProposal", "reason" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "action": { "type": "string", "description": "Action code to validate." }, "targetId": { "type": "string", "description": "Target conversation or resource ID." }, "allowed": { "type": "boolean", "description": "Whether the action may be executed." }, "requiredCapability": { "type": "string", "description": "Required capability code." }, "riskLevel": { "type": "string", "description": "low, medium, or high." }, "requiresProposal": { "type": "boolean", "description": "Whether a proposal or approval is required." }, "reason": { "type": "string", "description": "Redacted denial reason when not allowed." } } }, "PersonalWechatMessageTypeCatalog": { "type": "object", "required": [ "accountId", "schemaVersion", "messageTypes", "conversationTypes", "displayCategories", "resourceStatuses" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "schemaVersion": { "type": "string", "description": "Catalog schema version." }, "messageTypes": { "type": "array", "description": "Supported normalized message type codes.", "items": { "type": "string" } }, "conversationTypes": { "type": "array", "description": "Supported conversation type codes.", "items": { "type": "string" } }, "displayCategories": { "type": "array", "description": "Supported UI display category codes.", "items": { "type": "string" } }, "resourceStatuses": { "type": "array", "description": "Supported media resource status codes.", "items": { "type": "string" } } } }, "ProtocolRuntimeState": { "type": "object", "required": [ "accountId", "internalInstanceId", "bindSessionId", "cloudKeyId", "status", "updatedAt" ], "additionalProperties": false, "properties": { "accountId": { "type": "string", "description": "Product-level WeChat account ID." }, "internalInstanceId": { "type": "string", "description": "Internal protocol runtime ID." }, "bindSessionId": { "type": "string", "description": "Cloud bind session ID." }, "cloudKeyId": { "type": "string", "description": "Cloud key slot ID, not the raw WeChat key." }, "hostDeviceId": { "type": "string", "description": "Host device ID." }, "protocolDeviceType": { "type": "string", "description": "Protocol device profile type." }, "protocolDeviceProfileVersion": { "type": "string", "description": "Protocol device profile version." }, "status": { "type": "string", "description": "Runtime status." }, "bindStatus": { "type": "string", "description": "Bind session status." }, "workerId": { "type": "string", "description": "Worker ID when available." }, "workerLeaseExpiresAt": { "type": "string", "description": "Worker lease expiry time." }, "health": { "type": "object", "required": [], "additionalProperties": true, "properties": {} }, "recover": { "type": "object", "required": [], "additionalProperties": true, "properties": {} }, "updatedAt": { "type": "string", "description": "Update time." } } }, "MediaResourceResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/MediaResource" } } }, "RuntimeSummaryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProtocolRuntimeState" } } }, "PersonalWechatBindSessionResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatBindSession" } } }, "PersonalWechatProfileResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatProfile" } } }, "PersonalWechatCapabilityDirectoryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatCapabilityDirectory" } } }, "PersonalWechatScopeDirectoryResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatScopeDirectory" } } }, "PersonalWechatActionValidationResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatActionValidation" } } }, "PersonalWechatContactPageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatContactPage" } } }, "PersonalWechatLabelPageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatLabelPage" } } }, "PersonalWechatGroupPageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatGroupPage" } } }, "PersonalWechatGroupResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatGroup" } } }, "PersonalWechatGroupProtocolRequiredResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatGroupProtocolRequired" } } }, "PersonalWechatConversationPageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatConversationPage" } } }, "PersonalWechatMessagePageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatMessagePage" } } }, "PersonalWechatOfficialAccountPageResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatOfficialAccountPage" } } }, "PersonalWechatOfficialHubResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatOfficialHub" } } }, "PersonalWechatRecipientResolveResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatRecipientResolveResult" } } }, "PersonalWechatMessageTypeCatalogResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PersonalWechatMessageTypeCatalog" } } }, "ProtocolGenericTaskResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ProtocolGenericTask" } } }, "UnifiedProtocolTaskResponse": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UnifiedProtocolTask" } } }, "EmptyJsonRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Empty JSON request body for POST endpoints that currently use path parameters only.", "properties": {} }, "PersonalWechatAccountCreateRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Create or update a pending personal WeChat cloud account record without raw protocol fields.", "properties": { "accountId": { "type": "string", "description": "Optional client-provided product account ID." }, "displayName": { "type": "string", "description": "Display name for the pending cloud-mounted account." }, "deviceId": { "type": "string", "description": "Host device ID used only as client metadata." } } }, "PersonalWechatBindSessionCreateRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Create a cloud QR bind session. Raw WeChat Key, Data62, login state, and proxy credentials are forbidden.", "properties": { "deviceId": { "type": "string", "description": "Host device ID used by the local sidecar." }, "reconnectAccountId": { "type": "string", "description": "Existing account ID when reconnecting an occupied WeChat seat." }, "protocolDeviceType": { "type": "string", "description": "Requested protocol device profile type, such as ipad or mac." }, "localAccountCount": { "type": "integer", "description": "Local account count used for single-seat guardrails." } } }, "PersonalWechatActionValidateRequest": { "type": "object", "required": [ "action" ], "additionalProperties": false, "description": "Pre-validate a personal WeChat action before execution.", "properties": { "action": { "type": "string", "description": "Action code, for example message.send_text or task.retry." }, "targetId": { "type": "string", "description": "Target conversation, group, media, or task ID." }, "reason": { "type": "string", "description": "Redacted business reason." } } }, "ProtocolGenericTaskRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Generic protocol control task request. Private protocol fields, chat bodies, proxy credentials, and AI private data are forbidden.", "properties": { "sinceCursor": { "type": "string", "description": "Cursor for sync-like tasks." }, "cursor": { "type": "string", "description": "Compatibility alias for sinceCursor." }, "targetId": { "type": "string", "description": "Target conversation ID." }, "groupId": { "type": "string", "description": "Group chat ID." }, "userName": { "type": "string", "description": "Contact username or wxid surrogate." }, "query": { "type": "string", "description": "Search query." }, "ids": { "type": "array", "description": "Explicit target IDs.", "items": { "type": "string" } }, "limit": { "type": "integer", "description": "Requested result limit." }, "reason": { "type": "string", "description": "Redacted request reason." } } }, "FinderDetailRequest": { "type": "object", "required": [ "objectId" ], "additionalProperties": false, "description": "Create or read a Finder detail parsing task. Playback URLs, urlToken, decodeKey, comments, and raw protocol fields are forbidden.", "properties": { "objectId": { "type": "string", "description": "Finder object ID." }, "objectNonceId": { "type": "string", "description": "Finder object nonce ID when available." }, "finderUsername": { "type": "string", "description": "Finder username when available." }, "encryptedObjectId": { "type": "string", "description": "Encrypted object ID when available." }, "lastBuffer": { "type": "string", "description": "Pagination or continuation buffer when provided by the protocol layer." }, "traceId": { "type": "string", "description": "Optional caller trace ID." } } }, "MediaResourceRequest": { "type": "object", "required": [ "type", "sizeBytes" ], "additionalProperties": false, "description": "Register or create a media resource. Temporary WeChat URLs, urlToken, decodeKey, and proxy credentials are forbidden.", "properties": { "resourceId": { "type": "string", "description": "Optional caller-provided media resource ID." }, "type": { "type": "string", "description": "Media resource type, such as image, video, voice, file, finder_cover, or upload_asset." }, "resourceType": { "type": "string", "description": "Compatibility alias for type." }, "mimeType": { "type": "string", "description": "MIME type." }, "sizeBytes": { "type": "integer", "description": "Resource size in bytes." }, "fileName": { "type": "string", "description": "Original file name used only for object-key derivation." }, "objectKey": { "type": "string", "description": "Optional COS object key scoped by tenant/user/account." }, "messageId": { "type": "string", "description": "Related message ID when resolving an inbound media resource." }, "finderObjectId": { "type": "string", "description": "Related Finder object ID." }, "targetId": { "type": "string", "description": "Related conversation target ID." } } }, "MediaResourceBatchSignRequest": { "type": "object", "required": [ "resourceIds" ], "additionalProperties": false, "description": "Sign multiple media resources with short-lived URLs. Raw object storage secrets are never accepted.", "properties": { "resourceIds": { "type": "array", "description": "Media resource IDs to sign.", "items": { "type": "string" } } } }, "RecipientResolveRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Resolve display text or IDs into sendable conversation targets.", "properties": { "query": { "type": "string", "description": "Single recipient query." }, "queries": { "type": "array", "description": "Batch recipient queries.", "items": { "type": "string" } }, "targetId": { "type": "string", "description": "Compatibility input used as a recipient query." } } }, "RecoverRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Request protocol runtime recovery without sending raw login state or protocol secrets.", "properties": { "reason": { "type": "string", "description": "Redacted recovery reason." }, "workerId": { "type": "string", "description": "Preferred worker ID when manually targeting recovery." } } }, "TaskMutationRequest": { "type": "object", "required": [], "additionalProperties": false, "description": "Retry or cancel a queued task.", "properties": { "reason": { "type": "string", "description": "Redacted retry or cancellation reason." } } }, "ProtocolHealthUpdateRequest": { "type": "object", "required": [ "status" ], "additionalProperties": false, "description": "Internal worker account health update. Proxy credentials and protocol secrets are forbidden.", "properties": { "status": { "type": "string", "description": "Worker-reported account health status." }, "workerId": { "type": "string", "description": "Worker ID." }, "runtimeShardId": { "type": "string", "description": "Worker runtime shard ID." }, "workerCursor": { "type": "string", "description": "Worker event cursor." }, "queueLagMs": { "type": "integer", "description": "Queue lag in milliseconds." }, "latencyMs": { "type": "integer", "description": "Worker latency in milliseconds." }, "reconnectCount": { "type": "integer", "description": "Reconnect count." }, "lastError": { "type": "string", "description": "Redacted latest error." } } }, "ObjectStorageResult": { "type": "object", "required": [], "additionalProperties": false, "description": "Object storage writeback result without temporary WeChat URL secrets.", "properties": { "provider": { "type": "string", "description": "Object storage provider, normally cos." }, "bucket": { "type": "string", "description": "Bucket name." }, "region": { "type": "string", "description": "Bucket region." }, "objectKey": { "type": "string", "description": "COS object key." }, "mimeType": { "type": "string", "description": "MIME type." }, "sizeBytes": { "type": "integer", "description": "Object size in bytes." }, "checksum": { "type": "string", "description": "Checksum when available." } } }, "ProtocolMediaResourceResultRequest": { "type": "object", "required": [ "resourceId" ], "additionalProperties": false, "description": "Internal worker media-resource writeback. Temporary URLs, urlToken, decodeKey, and raw protocol secrets are forbidden.", "properties": { "resourceId": { "type": "string", "description": "Media resource ID." }, "status": { "type": "string", "description": "available, failed, pending, or uploading." }, "mimeType": { "type": "string", "description": "MIME type." }, "sizeBytes": { "type": "integer", "description": "Object size in bytes." }, "objectStorage": { "$ref": "#/components/schemas/ObjectStorageResult" }, "checksum": { "type": "string", "description": "Checksum when available." }, "errorCode": { "type": "string", "description": "Failure code when available." }, "errorMessage": { "type": "string", "description": "Redacted failure message when available." } } } }, "responses": { "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Unauthorized": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "Capability or account access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "tags": [ { "name": "Health", "description": "Readiness and deployment health probes." }, { "name": "Personal WeChat Accounts", "description": "Personal WeChat account creation, binding, profile, online state, runtime summary, and recovery." }, { "name": "Personal WeChat Events", "description": "Cursor-based personal WeChat protocol event reads with redacted payload boundaries." }, { "name": "Personal WeChat Conversations", "description": "Conversation and normalized message reads built from cloud-side event cache." }, { "name": "Personal WeChat Messaging", "description": "Message sync, message normalization, message type catalog, text send tasks, and send status reads." }, { "name": "Personal WeChat Contacts", "description": "Contacts, labels, contact search tasks, and recipient resolution." }, { "name": "Personal WeChat Groups", "description": "Group list, search, detail, member, QR code, and group sync tasks." }, { "name": "Personal WeChat Official Accounts", "description": "Official account list, hub, and official account message reads." }, { "name": "Personal WeChat Media", "description": "Object storage entitlement, media resource registration, upload, status, and short-lived signing." }, { "name": "Personal WeChat Finder and SNS", "description": "Finder search/detail tasks and SNS timeline or user-page tasks." }, { "name": "Personal WeChat Tasks", "description": "Unified task status, retry, cancellation, and action pre-validation." }, { "name": "Enterprise WeChat Reserved", "description": "Reserved enterprise WeChat capability namespace for future independent implementation." }, { "name": "Protocol Workers", "description": "Internal protocol worker claim, health, and result writeback endpoints." } ] }