{"openapi":"3.1.0","info":{"title":"WuKongIM Trusted Message Sending Beta Subset","version":"3.0.0-beta-snapshot","description":"A non-exhaustive Product HTTP contract for ordinary durable Channel sends from a trusted backend. The route has no built-in authentication.","x-i18n":{"zh":{"title":"WuKongIM 受信消息发送 Beta 子集","description":"供受信后端发送普通持久 Channel 消息的非完整 Product HTTP 合同；该路由没有内建鉴权。"}}},"x-wukongim-scope":"non-exhaustive-trusted-message-sending-beta","servers":[{"url":"http://127.0.0.1:5001","description":"Default Product HTTP listener for a local single-node cluster","x-i18n":{"zh":{"description":"本地单节点集群的默认 Product HTTP 监听地址"}}}],"tags":[{"name":"Message Sending","description":"Ordinary durable Channel message submission.","x-i18n":{"zh":{"description":"提交普通持久 Channel 消息。"}}}],"paths":{"/message/send":{"post":{"operationId":"sendChannelMessage","summary":"Send a durable Channel message","description":"A trusted backend submits one ordinary durable message. HTTP 200 is transport success; inspect reason for the business result.","x-i18n":{"zh":{"summary":"发送持久 Channel 消息","description":"受信后端提交一条普通持久消息。HTTP 200 仅表示传输成功，业务结果必须检查 reason。"}},"tags":["Message Sending"],"x-wukongim-trust":"trusted-backend-only","x-codeSamples":[{"lang":"bash","label":"Trusted backend (cURL)","source":"# Run only from the trusted backend boundary.\ncurl --fail-with-body \\\n  --request POST \\\n  --url http://127.0.0.1:5001/message/send \\\n  --header 'content-type: application/json' \\\n  --data '{\"from_uid\":\"system\",\"channel_id\":\"alice\",\"channel_type\":1,\"client_msg_no\":\"order-20260828-0001\",\"payload\":\"eyJ0eXBlIjoib3JkZXJfdXBkYXRlIn0=\"}'","x-i18n":{"zh":{"label":"受信后端（cURL）","source":"# 只在受信后端边界运行。\ncurl --fail-with-body \\\n  --request POST \\\n  --url http://127.0.0.1:5001/message/send \\\n  --header 'content-type: application/json' \\\n  --data '{\"from_uid\":\"system\",\"channel_id\":\"alice\",\"channel_type\":1,\"client_msg_no\":\"order-20260828-0001\",\"payload\":\"eyJ0eXBlIjoib3JkZXJfdXBkYXRlIn0=\"}'"}}}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChannelMessageRequest"},"example":{"from_uid":"system","channel_id":"alice","channel_type":1,"client_msg_no":"order-20260828-0001","payload":"eyJ0eXBlIjoib3JkZXJfdXBkYXRlIn0="}}}},"responses":{"200":{"$ref":"#/components/responses/SendCompleted"},"400":{"$ref":"#/components/responses/SendBadRequest"},"404":{"$ref":"#/components/responses/ChannelNotFound"},"408":{"$ref":"#/components/responses/SendTimedOut"},"500":{"$ref":"#/components/responses/SendInternalError"},"503":{"$ref":"#/components/responses/SendUnavailable"}}}}},"components":{"schemas":{"SendChannelMessageRequest":{"type":"object","description":"The supported ordinary durable-send shape.","x-i18n":{"zh":{"description":"受支持的普通持久消息发送结构。"}},"additionalProperties":false,"required":["from_uid","channel_id","channel_type","client_msg_no","payload"],"properties":{"from_uid":{"type":"string","minLength":1,"pattern":"\\S","description":"Caller-supplied sender UID; it is not authenticated by this route.","x-i18n":{"zh":{"description":"调用方提供的发送者 UID；该路由不会鉴定其身份。"}}},"channel_id":{"type":"string","minLength":1,"pattern":"\\S","description":"Target Channel ID. For a person Channel, use the peer UID.","x-i18n":{"zh":{"description":"目标 Channel ID；个人 Channel 使用对端 UID。"}}},"channel_type":{"type":"integer","format":"uint8","minimum":1,"maximum":255,"description":"Channel Type from the shared protocol dictionary.","x-i18n":{"zh":{"description":"共享协议字典中的 Channel Type。"}}},"client_msg_no":{"type":"string","minLength":1,"pattern":"\\S","description":"Stable client idempotency key. Reuse it for bounded retries of the same payload.","x-i18n":{"zh":{"description":"稳定的客户端幂等键；同一 Payload 有界重试时复用。"}}},"payload":{"type":"string","minLength":1,"contentEncoding":"base64","description":"Base64 encoding of the message payload bytes.","x-i18n":{"zh":{"description":"消息 Payload 字节的 Base64 编码。"}}}}},"SendChannelMessageResponse":{"type":"object","description":"Message identity, Channel sequence, and protocol Reason Code.","x-i18n":{"zh":{"description":"消息标识、Channel 序号与协议 Reason Code。"}},"additionalProperties":false,"required":["message_id","message_seq","reason"],"properties":{"message_id":{"type":"integer","format":"int64","description":"Server message ID; meaningful when reason is success.","x-i18n":{"zh":{"description":"服务端消息 ID；reason 成功时有效。"}}},"message_seq":{"type":"integer","format":"uint64","minimum":0,"description":"Committed sequence in this Channel; meaningful when reason is success.","x-i18n":{"zh":{"description":"消息在该 Channel 内的已提交序号；reason 成功时有效。"}}},"reason":{"type":"integer","format":"uint8","minimum":0,"maximum":255,"enum":[1,2,3,4,5,9,11,13,15,18,19,24,25],"description":"Protocol Reason Code. HTTP 200 does not mean business success; only ReasonSuccess (1) confirms acceptance.","x-i18n":{"zh":{"description":"协议 Reason Code。HTTP 200 不代表业务成功；仅 ReasonSuccess（1）确认接受。"}}}}},"SendError":{"type":"object","description":"Message-send HTTP error. Unlisted text is not a stable machine contract.","x-i18n":{"zh":{"description":"消息发送 HTTP 错误；未列出的文本不是稳定机器合同。"}},"additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error detail.","x-i18n":{"zh":{"description":"供人阅读的错误详情。"}}}}},"RetryRequiredError":{"type":"object","description":"The Channel authority route must be refreshed before a bounded retry.","x-i18n":{"zh":{"description":"有界重试前必须刷新 Channel 权威路由。"}},"additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","const":"retry required","description":"Retry category for stale or unavailable authority routing.","x-i18n":{"zh":{"description":"权威路由陈旧或不可用时的重试类别。"}}}}},"MaintenanceError":{"type":"object","description":"Controller restore maintenance currently fences Product HTTP writes.","x-i18n":{"zh":{"description":"Controller 恢复维护当前阻止 Product HTTP 写入。"}},"additionalProperties":false,"required":["error","message"],"properties":{"error":{"type":"string","const":"maintenance","description":"Machine-readable maintenance category.","x-i18n":{"zh":{"description":"机器可读的维护类别。"}}},"message":{"type":"string","const":"restore maintenance is active","description":"Current maintenance detail.","x-i18n":{"zh":{"description":"当前维护详情。"}}}}}},"responses":{"SendCompleted":{"description":"HTTP request completed; inspect reason for the business result.","x-i18n":{"zh":{"description":"HTTP 请求已完成；业务结果必须检查 reason。"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChannelMessageResponse"},"example":{"message_id":123456789,"message_seq":42,"reason":1}}}},"SendBadRequest":{"description":"Invalid request, payload, or Channel identity.","x-i18n":{"zh":{"description":"请求、Payload 或 Channel 标识无效。"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendError"},"example":{"error":"invalid request"}}}},"ChannelNotFound":{"description":"The target Channel was not found.","x-i18n":{"zh":{"description":"未找到目标 Channel。"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendError"},"example":{"error":"channel not found"}}}},"SendTimedOut":{"description":"The request was canceled or timed out.","x-i18n":{"zh":{"description":"请求已取消或超时。"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendError"},"examples":{"canceled":{"value":{"error":"request canceled"}},"timeout":{"value":{"error":"request timeout"}}}}}},"SendInternalError":{"description":"An internal send dependency failed. Error text is not stable.","x-i18n":{"zh":{"description":"内部发送依赖失败；错误文本不稳定。"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendError"},"example":{"error":"message usecase not configured"}}}},"SendUnavailable":{"description":"Refresh routing and retry, or wait for restore maintenance to end.","x-i18n":{"zh":{"description":"刷新路由后重试，或等待恢复维护结束。"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RetryRequiredError"},{"$ref":"#/components/schemas/MaintenanceError"}]},"examples":{"retryRequired":{"value":{"error":"retry required"}},"maintenance":{"value":{"error":"maintenance","message":"restore maintenance is active"}}}}}}}}}