开发文档
能力中心
应用市场
WebOffice
开发者后台

发送消息 ​

用于应用通过WPS协作给用户发送消息，支持多种消息类型，使用时需注意以下几点：

  1. 接收者需要在应用可用范围内。应用可用范围可通过获取应用可用范围接口获取
  2. 往群聊会话发送消息时，需要该应用机器人在群聊内
  3. 应用机器人发送的消息最多不超过 5000 个字符
  4. 支持向 5 类对象发送消息：指定用户、指定会话、指定部门、指定企业、关联组织。但需注意的是，单次调用里面，不同类别的接收对象，其所属的企业必须为同一个，即授权企业（即不支持同时向不同企业的接收对象发送同一条消息）

请求说明 ​

请求地址https://openapi.wps.cn/v7/messages/batch_create
请求方法POST
签名方式KSO-1
权限要求查询和管理会话消息（应用授权） kso.chat_message.readwrite

请求头（Header） ​

Header 名称参数类型是否必填说明
Content-Typestring是使用：application/json
X-Kso-Datestring是RFC1123 格式的日期，例: Wed, 23 Jan 2013 06:43:08 GMT
X-Kso-Authorizationstring是KSO-1 签名值，详见《签名方法》
Authorizationstring是授权凭证，格式为：Bearer {access_token}

请求体（Body） ​

名称参数类型是否必填说明
typestring[enum]是消息类型
text：文本；rich_text：富文本；image：图片；
file：文件；audio：音频；video：视频；card：卡片消息
receiversarray[object]是消息接收者
∟ partner_idstring否关联组织 id，当接收者为关联组织时传
∟ receiver_idsarray[string]是接收者 id 列表
∟ typestring[enum]是接收者类型
chat：会话；company：企业；dept：部门；user：企业成员；
enterprise_partner：关联组织；enterprise_partner_dept：关联组织部门；enterprise_partner_user：关联组织成员
mentionsarray[object]否被 at 的人员列表，具体用法见下文详细描述
∟ idstring是指定聊天消息中 at 操作的实体索引 id。与消息正文中相应 <at id={index}> 标记中的 {index} 值匹配
∟ identityobject否被 at 的用户信息，当 at 所有人时该值为空
∟ ∟ company_idstring是用户所属企业id
∟ ∟ idstring是用户id
∟ ∟ typestring[enum]是身份类型
user：用户；
∟ typestring[enum]是at 操作对象类型
all：所有人；user：用户
contentobject是消息内容，需要根据发送的消息类型 type，传递不同的对象
∟ textobject否文本消息，见下文详细描述
∟ rich_textobject否富文本消息，见下文详细描述
∟ imageobject否图片消息，见下文详细描述
∟ fileobject否文件消息，见下文详细描述
∟ audioobject否音频消息，见下文详细描述
∟ videoobject否视频消息，见下文详细描述
∟ cardobject否卡片消息，见下文详细描述

请求地址示例 ​

[POST] https://openapi.wps.cn/v7/messages/batch_create

请求体示例 ​

json
{
  "type": "string[enum]",
  "receivers": [
    {
      "partner_id": "string",
      "receiver_ids": [
        "string"
      ],
      "type": "string[enum]"
    }
  ],
  "mentions": [
    {
      "id": "string",
      "identity": {
        "company_id": "string",
        "id": "string",
        "type": "user"
      },
      "type": "user"
    }
  ],
  "content": {
    // 注意：根据不同 type，传递不同消息内容结构
  }
}

消息内容（content）结构说明 ​

发送消息时，需要根据发送消息的类型 消息类型，传递不同的消息内容 content，支持的消息类型如下：

文本（text） ​

消息类型为文本 type=text 时，传递的内容 content 对象

名称参数类型是否必填说明
textobject否文本消息
支持通过在消息体插入标签的方式 at 人
例子：你好 <at id="0"> 张三 </at>
∟ contentstring是文本内容
∟ typestring[enum]否文本类型
plain：纯文本；markdown
json
{
  // 文本
  "type": "text",
  "receivers": [],
  "mentions": [],
  "content": {
    "text": {
      "content": "string",
      "type": "string[enum]"
    }
  }
}

富文本（rich_text） ​

消息类型为富文本 type=rich_text 时，传递的内容 content 对象

名称参数类型是否必填说明
rich_textobject否富文本消息
∟ elementsarray[object]是富文本消息内容
∟ ∟ typestring[enum]是富文本元素类型
ol：有序列表；ul：无序列表；nl：换行；text：普通文本；
emoji：表情；custom_emoji：自定义表情；mention：at 人；image：图片
∟ ∟ alt_textstring是代替文本摘要，当客户端无法解析则取该字段
∟ ∟ indentinteger是缩进
∟ ∟ indexinteger是第几行
∟ ∟ elementsarray[object]否子元素列表，与父元素 element 结构相同（递归）
∟ ∟ text_contentobject否【1】纯文本内容， 当富文本元素类型为表情 emoji 时使用
∟ ∟ ∟ contentstring是文本内容
∟ ∟ ∟ typestring[enum]否文本类型
plain：纯文本；markdown
∟ ∟ style_text_contentobject否【2】有样式的文本内容，当富文本元素类型为普通文本 text 时使用
∟ ∟ ∟ styleobject是元素样式
∟ ∟ ∟ ∟ boldboolean是加粗
∟ ∟ ∟ ∟ colorstring是RGBA 16 进制描述，例如：#FF0000FF，最后两位为透明度
∟ ∟ ∟ ∟ italicboolean是斜体
∟ ∟ mention_contentobject否【3】at 人的内容，当富文本元素类型为 at 人 mention 时使用
∟ ∟ ∟ identityobject否被 at 用户的 id，当 at 所有人时该值为空
∟ ∟ ∟ ∟ avatarstring是用户头像
∟ ∟ ∟ ∟ company_idstring是企业 id
∟ ∟ ∟ ∟ idstring是用户信息
∟ ∟ ∟ ∟ namestring是用户名称
∟ ∟ ∟ ∟ typestring[enum]是身份类型
user：用户；sp：服务主体
∟ ∟ ∟ textstring是被 at 的文本内容
∟ ∟ image_contentobject否【4】图片内容，当富文本元素类型为自定义表情 custom_emoji 或 图片 image 时使用
∟ ∟ ∟ sizeinteger否图片大小（B）
∟ ∟ ∟ heightinteger否高度（px）
∟ ∟ ∟ widthinteger否宽度（px）
∟ ∟ ∟ namestring否图片名称
∟ ∟ ∟ typestring否图片格式，可传值：
image/png；image/jpg；image/gif；image/webp
∟ ∟ ∟ storage_keystring是图片存储 key
∟ ∟ ∟ thumbnail_typestring否缩略图片格式，可传值：
image/png；image/jpg；image/gif；image/webp
∟ ∟ ∟ thumbnail_storage_keystring否缩略图片存储 key
∟ ∟ link_contentobject否【5】链接的内容，当富文本元素类型为 link 时使用
∟ ∟ ∟ textstring是文本内容
∟ ∟ ∟ urlstring是url 链接
json
{
  // 富文本
  "type": "rich_text",
  "receivers": [],
  "mentions": [],
  "content": {
    "rich_text": {
      "elements": [
        {
          "type": "string[enum]",
          "alt_text": "string",
          "indent": 0,
          "index": 0,
          "elements": [
            {
              // 与父元素 elements 结构相同（递归）
            }
          ],
          "text_content": {
            "content": "string",
            "type": "string[enum]"
          },
          "style_text_content": {
            "style": {
              "bold": false,
              "color": "string",
              "italic": false
            },
            "text": "string"
          },
          "mention_content": {
            "identity": {
              "avatar": "string",
              "company_id": "string",
              "id": "string",
              "name": "string",
              "type": "string[enum]"
            },
            "text": "string",
            "type": "string[enum]"
          },
          "image_content": {
            "height": 0,
            "name": "string",
            "size": 0,
            "storage_key": "string",
            "thumbnail_storage_key": "string",
            "thumbnail_type": "string",
            "type": "string",
            "width": 0
          },
          "link_content": {
            "text": "string",
            "url": "string"
          }
        }
      ]
    }
  }
}

图片（image） ​

消息类型为图片 type=image 时，传递的内容 content 对象

名称参数类型是否必填说明
imageobject否图片消息
∟ typestring否图片格式，可传值：
image/png；image/jpg；image/gif；image/webp
∟ thumbnail_typestring否缩略图片格式，可传值：
image/png；image/jpg；image/gif；image/webp
∟ namestring否图片名称
∟ sizeinteger否图片大小（B），不传默认按原图比例和大小展示
∟ widthinteger否宽度（px），不传默认按原图比例和大小展示
∟ heightinteger否高度（px），不传默认按原图比例和大小展示
∟ storage_keystring是图片存储 key
∟ thumbnail_storage_keystring否缩略图片存储 key
json
{
  // 图片
  "type": "image/png",
  "receivers": [],
  "mentions": [],
  "content": {
    "image": {
      "type": "string",
      "thumbnail_type": "string",
      "name": "string",
      "size": 0,
      "width": 0,
      "height": 0,
      "storage_key": "string",
      "thumbnail_storage_key": "string"
    }
  }
}

文件（file） ​

消息类型为文件 type=file 时，传递的内容 content 对象

  • 发送本地文件，即文件类型为 local
名称参数类型是否必填说明
fileobject否文件消息
∟ typestring[enum]是文件类型：固定为local：本地文件
∟ localobject否本地文件
∟ ∟ namestring否文件名称
∟ ∟ sizeinteger否文件大小（B）
∟ ∟ storage_keystring是文件存储 key
json
{
  // 文件
  "type": "file",
  "receivers": [],
  "mentions": [],
  "content": {
    "file": {
      // 本地文件
      "type": "local",
      "local": {
        "name": "string",
        "size": 0,
        "storage_key": "string"
      }
    }
  }
}

音频（audio） ​

消息类型为音频 type=audio 时，传递的内容 content 对象

名称参数类型是否必填说明
audioobject否音频消息
∟ mediaobject是音频媒体信息
∟ ∟ channelsinteger否通道数
∟ ∟ codecstring[enum]否编码格式
amr
∟ ∟ durationinteger否播放时长（s）
∟ ∟ formatstring[enum]否文件格式
wav
∟ ∟ sample_bitsinteger否比特率
∟ ∟ sample_rateinteger否采用率
∟ ∟ sizeinteger否文件大小（B）
∟ storage_keystring是音频文件存储 key
json
{
  // 音频
  "type": "audio",
  "receivers": [],
  "mentions": [],
  "content": {
    "audio": {
      "media": {
        "channels": 0,
        "codec": "string[enum]",
        "duration": 0,
        "format": "string[enum]",
        "sample_bits": 0,
        "sample_rate": 0,
        "size": 0
      },
      "storage_key": "string"
    }
  }
}

视频（video） ​

消息类型为音频 type=video 时，传递的内容 content 对象

名称参数类型是否必填说明
videoobject否视频消息
∟ mediaobject是视频媒体信息
∟ ∟ codecstring[enum]否编码格式
h.264
∟ ∟ cover_storage_keystring否视频文件封面图片存储 key
∟ ∟ durationinteger否播放时长（s）
∟ ∟ formatstring[enum]否文件格式
mp4
∟ ∟ heightinteger否高度（px）
∟ ∟ sizeinteger否文件大小（B）
∟ ∟ widthinteger否宽度（px）
∟ storage_keystring是视频文件存储 key
json
{
  // 视频
  "type": "audio",
  "receivers": [],
  "mentions": [],
  "content": {
    "video": {
      "media": {
        "codec": "string[enum]",
        "cover_storage_key": "string",
        "duration": 0,
        "format": "string[enum]",
        "height": 0,
        "size": 0,
        "width": 0
      },
      "storage_key": "string"
    }
  }
}

卡片（card） ​

消息卡片是应用接入WPS协作机器人发送消息时的一种消息类型。消息卡片提供了丰富的组件，支持开发者按需组合配置消息卡片。详细说明可看WPS协作卡片介绍 和 WPS协作卡片结构说明

为了提升卡片的搭建效率，WPS开放平台也为开发者提供了可视化的消息卡片搭建工具，开发者可进入开发者后台-应用能力-WPS协作机器人-发送消息-API发送-消息卡片编辑器处进行配置。

消息类型为卡片 type=card 时，传递的内容 content 对象

名称参数类型是否必填说明
cardobject否卡片消息
∟ config是object
∟ link否object卡片整体的跳转链接
∟ i18n_items是array卡片的内容，支持多语言
json
{
  "type": "card",
  "receivers": [],
  "mentions": [],
  "content": {
    "card": {
      "config": {
      },
      "i18n_items": [
        {
        }
      ],
      "link": {
      }
    }
  }
}

如何在消息内@人 ​

消息接口支持在markdown格式的文本内，通过在消息体 content 中插入<at>标签的方式@人。目前支持markdown文本的消息类型有：文本（text）、富文本（rich_text）、卡片（card）

使用步骤如下：

1.在对应消息类型的content内，使用<at>标签的方式写入@内容，有2种使用格式:

  • @单个用户：<at id=\"2\">展示名称</at>
  • @所有人：<at id=\"1\">所有人</at>，id固定为1

请注意，上述的id仅用来代表索引，在下述第2步中会使用到，并不是用户user_id

2.在该接口的请求体mentions部分，传参上述的索引和具体的用户user_id。具体写法和对应关系请看示例图：

艾特人

响应体 ​

名称参数类型说明
codeinteger响应代码。非 0 表示失败，参照《状态码说明》
msgstring响应信息
dataobject响应数据
∟ idstring消息 id
∟ chat_idstring会话 id
∟ quote_msg_idstring被引用的消息 id
∟ typestring[enum]消息类型
text：文本；rich_text：富文本；image：图片；
file：文件；audio：音频；video：视频；card：卡片消息
∟ positioninteger会话消息位置索引，严格连续递增
∟ ctimeinteger消息创建时间
∟ mentionsarray[object]被 at 的人员列表
∟ ∟ idstring指定聊天消息中 at 操作的实体索引 id。与消息正文中相应 <at id={index}> 标记中的 {index} 值匹配
∟ ∟ identityobject被 at 的用户信息，当 at 所有人时该值为空
∟ ∟ ∟ avatarstring用户头像
∟ ∟ ∟ company_idstring企业 id
∟ ∟ ∟ idstring用户信息
∟ ∟ ∟ namestring用户名称
∟ ∟ ∟ typestring[enum]身份类型
user：用户；sp：服务主体
∟ ∟ typestring[enum]at 操作对象类型
all：所有人；user：用户
∟ senderobject发送者，包括用户、应用和机器人
∟ ∟ avatarstring用户头像
∟ ∟ company_idstring企业 id
∟ ∟ idstring用户信息
∟ ∟ namestring用户名称
∟ ∟ typestring[enum]身份类型
user：用户；sp：服务主体
∟ recallobject消息撤回信息
∟ ∟ operator_idstring撤回消息操作者 id
∟ contentobject消息内容
∟ ∟ textobject文本消息，见上文详细描述，相同的定义
∟ ∟ rich_textobject富文本消息，见上文详细描述，相同的定义
∟ ∟ imageobject图片消息，见上文详细描述，相同的定义
∟ ∟ fileobject文件消息，见上文详细描述，相同的定义
∟ ∟ audioobject音频消息，见上文详细描述，相同的定义
∟ ∟ videoobject视频消息，见上文详细描述，相同的定义
∟ ∟ cardobject卡片消息，见上文详细描述，相同的定义

响应体示例 ​

json
{
  "data": {
    "id": "string",
    "chat_id": "string",
    "quote_msg_id": "string",
    "type": "string[enum]",
    "position": 0,
    "ctime": 0,
    "mentions": [
      {
        "id": "string",
        "identity": {
          "avatar": "string",
          "company_id": "string",
          "id": "string",
          "name": "string",
          "type": "string[enum]"
        },
        "type": "string[enum]"
      }
    ],
    "sender": {
      "avatar": "string",
      "company_id": "string",
      "id": "string",
      "name": "string",
      "type": "string[enum]"
    },
    "recall": {
      "operator_id": "string"
    },
    "ext_attrs": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "content": {
      // 根据不同的 type，返回不同内容
    }
  },
  "code": 0,
  "msg": "string"
}
回到旧版