发送消息

API 说明

用于应用通过WPS协作给用户或会话发送消息，支持多种消息类型。

注意事项：

接收者需要在应用可用范围内。
应用机器人发送的消息最多不超过 5000 个字符。
接收者类型支持 chat（会话）、user（企业成员）、enterprise_partner_user（关联组织成员）
给群组发送消息时，机器人需要在该群组中。

使用限制：

单个应用限制20QPS。

请求说明

字段	值
请求地址	https://openapi.wps.cn/v7/messages/create
HTTP 方法	`POST`
签名方式	KSO-1
限频策略	单个应用限制20QPS
权限要求	应用授权：`app:kso.chat_message.readwrite`（查询和管理会话消息）应用授权：`app:kso.mcp_message.readwrite`（MCP协作消息与会话管理）

请求头（Headers）

Header 名称	参数类型	是否必填	可选值	限制	示例	描述
Content-Type	string	是	`application/json`	固定为【application/json】	`application/json`	内容类型，固定为 JSON 格式
X-Kso-Id-Type	string	否	`internal`：内部 ID `external`：外部 ID	-	`internal`	开放 ID 类型，默认 internal，目前仅用户 ID 和部门 ID 存在转换
X-Kso-Date	string	是	-	必须符合 RFC1123 规范	`Sun, 25 May 2026 02:48:00 GMT`	请求时间，用于防重放攻击等
X-Kso-Authorization	string	是	-	-	`KSO-1 AK123456:ce8df66877175e5198c8ea1362ffddf82e4941c6f25a4ca205a1ad09d0faaf03`	KSO-1 签名值，详见签名方法
Authorization	string	是	-	必须以 Bearer 开头	`Bearer {access_token}`	授权凭证，格式为：`Bearer {access_token}`，获取方式详见认证授权概述

请求体（Body）

参数名称	参数类型	是否必填	可选值	限制	示例	描述
type	string	是	`text`：文本 `rich_text`：富文本 `image`：图片 `file`：文件 `audio`：音频 `video`：视频 `card`：卡片消息 `meeting`：会议消息 `calendar`：日程消息 `share_user`：个人名片消息 `vote`：投票	-	`text`	消息类型，目前只支持text、rich_text、image、file、audio、video、card类型
content	object	是	-	-		消息内容，需要根据发送的消息类型 `type`，传递不同的对象。详见：消息内容（content）结构说明
receiver	object	是	-	-		消息接收者
∟ receiver_id	string	是	-	最小长度1	`oc_example_001`	接收者身份标识，根据 receiver_type 传入对应标识（chat_id / user_id / dept_id 等）
∟ type	string	是	`chat`：会话 `user`：企业成员 `enterprise_partner_user`：关联组织成员	-	`chat`	接收者类型，当前支持chat、user、enterprise_partner_user类型
∟ partner_id	string	否	-	-	`demo_partner_id`	关联组织id，当接收者为关联组织时传，可通过关联组织管理接口获取
mentions	array[object]	否	-	-		被 at 的人员列表，最多不能超过100个，具体用法详见：消息内容（content）结构说明
∟ id	string	是	-	-	`0`	指定聊天消息中at操作的实体索引ID。与消息正文中相应 `<at id={index}>` 标记中的 `{index}` 值匹配。
∟ type	string	是	`all`：所有人 `user`：用户	-	`user`	at操作对象类型
∟ identity	object	否	-	-		被at的用户信息，当at所有人时该值为空
∟ ∟ id	string	是	-	-	`uid_example_001`	身份ID，可通过通讯录相关接口获取
∟ ∟ type	string	是	`user`：用户	-	`user`	身份类型
∟ ∟ company_id	string	否	-	-	`company_001`	企业 ID

请求示例

cURL

bash

curl -X POST "https://openapi.wps.cn/v7/messages/create" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -H "X-Kso-Id-Type: internal" \
  -H "X-Kso-Date: Sun, 25 May 2026 02:48:00 GMT" \
  -H "X-Kso-Authorization: {{kso1_signature}}" \
  -d '{
    "type": "text",
    "content": {
      "text": {
        "content": "你好，这是一条测试消息"
      }
    },
    "receiver": {
      "receiver_id": "oc_example_001",
      "type": "chat"
    },
    "mentions": [
      {
        "id": "0",
        "type": "user",
        "identity": {
          "id": "uid_example_001",
          "type": "user",
          "company_id": "company_001"
        }
      }
    ]
  }'

响应体（Response）

参数名称	参数类型	可选值	限制	描述
code	integer	-	-	错误码。非 0 表示失败
msg	string	-	-	错误描述
data	object	-	-	业务数据
∟ chat_id	string	-	-	会话 ID
∟ message_id	string	-	-	消息id
∟ ctime	integer	-	-	消息创建时间
∟ type	string	`text`：文本 `rich_text`：富文本 `image`：图片 `file`：文件 `audio`：音频 `video`：视频 `card`：卡片消息 `meeting`：会议消息 `calendar`：日程消息 `share_user`：个人名片消息 `vote`：投票	-	消息类型，目前只支持text、rich_text、image、file、audio、video、card类型
∟ content	object	-	-	消息内容，详见：消息内容（content）结构说明
∟ mentions	array[object]	-	-	被 @ 的人员列表，具体用法详见：消息内容（content）结构说明
∟ ∟ id	string	-	-	指定聊天消息中at操作的实体索引ID
∟ ∟ type	string	`all`：所有人 `user`：用户	-	at操作对象类型
∟ ∟ identity	object	-	-	被at的用户信息，当at所有人时该值为空
∟ ∟ ∟ id	string	-	-	身份ID
∟ ∟ ∟ type	string	`user`：用户 `sp`：服务主体 `unknown`：未知	-	身份类型
∟ ∟ ∟ company_id	string	-	-	企业 ID

响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "chat_id": "oc_example_001",
    "message_id": "msg_example_001",
    "ctime": 1748141280,
    "type": "text",
    "content": {
      "text": {
        "content": "你好，这是一条测试消息"
      }
    },
    "mentions": [
      {
        "id": "0",
        "type": "user",
        "identity": {
          "id": "uid_example_001",
          "type": "user",
          "company_id": "company_001"
        }
      }
    ]
  }
}

错误码

HTTP状态码	错误码	错误描述	排查建议
400	400000001	流量超出	请降低请求频率后重试。
400	400000002	请求参数格式有误	请从msg中提取具体格式错误的请求参数信息，调整为符合限制要求后再次请求。
400	400000003	请求参数取值无效	请从msg中提取具体取值无效的请求参数信息，调整为符合限制要求后再次请求。注意，只能在可选值列提供的枚举中选值。
400	400000004	请求参数不支持	请检查请求参数是否包含不支持的字段，移除后重试。
400	400000007	非法参数	请检查请求参数的合法性，修正后重试。
400	400000103	资源不存在	请确认请求中引用的资源（如会话、用户等）是否存在。
400	400000104	资源已经存在	请确认是否重复操作，避免重复创建已存在的资源。
400	400000105	数目限制超出	请减少批量操作的数量，确保不超出限制后重试。
400	400000106	长度限制超出	请从msg中提取具体超长的请求参数信息，调整为符合限制要求后再次请求。
400	400413001	会话不存在	请确认 receiver_id 对应的会话是否存在，或会话是否已被解散。
400	400413002	用户不在会话内	请确认发送消息的应用或用户是否已加入目标会话。
400	400413003	不支持的会话类型	请确认目标会话类型是否在当前接口支持范围内。
401	401000001	认证错误	请检查 Authorization 中的 access_token 是否有效，或 KSO-1 签名是否正确。
403	403000001	无权限	请确认应用是否已获得所需权限范围（scopes），或用户是否有操作权限。
403	403000002	策略判定拒绝	请检查是否触发了安全策略限制，联系管理员确认。
415	415000001	不支持的 ContentType	固定使用application/json，暂不支持其他枚举。
429	429000001	请求太频繁	请降低请求频率，建议稍后重试。
500	500000002	断路器已打开	服务熔断，请勿频繁重试请求，建议5分钟后重试或立即联系客服人员。
500	500000003	存储服务错误	存储服务异常，请稍后重试或联系客服人员。
500	500000004	服务端其他错误	服务端内部错误，请勿频繁重试请求，建议10分钟后重试或立即联系客服人员。
503	503000001	服务数据升级中	服务正在进行数据升级，请稍后重试。