消息推送

PDF版下载

如流开放了消息发送接口，企业可以使用这些接口让企业应用与用户间进行双向通信。

推送消息

向成员推送消息

请求方式：POST（HTTPS）

请求地址：https://api.im.baidu.com/api/message/send?access_token=ACCESS_TOKEN

请求body：（每种类型的消息请求body不同，详见消息推送格式）

参数说明：

权限要求：

管理组须拥有指定应用的使用权限，消息接受者必须处于应用的可见范围内并已经关注应用

返回结果：

{
    "errcode": 0,
    "errmsg": "ok",
    "invaliduser": "UserID1",
    "invalidparty": "PartyID1",
    "invalidtag": "TagID1"
}

参数说明：

消息推送格式

文本消息

消息示例：

{
    "touser": "UserID1|UserID2|UserID3",
    "toparty": " PartyID1 | PartyID2 ",
    "totag": " TagID1 | TagID2 ",
    "msgtype": "text",
    "agentid": "1",
    "text": {
        "content": "Holiday Request For ****(http://www.baidu.com)"
    }
}

参数说明：

图文消息

消息示例：

{
    "touser": "UserID1|UserID2|UserID3",
    "toparty": " PartyID1|PartyID2 ",
    "totag": " TagID1|TagID2 ",
    "msgtype": "news",
    "agentid": "1",
    "news": {
        "articles":[
            {
                "title": "Title1",
                "description": "Description1",
                "url": "https://m.baidu.com",
                "picurl": "https://www.baidu.com/img/flexible/logo/plus_logo_web_2.png"
            },
            {
                "title": "Title2",
                "description": "Description2",
                "url": "https://m.baidu.com",
                "picurl": "https://www.baidu.com/img/flexible/logo/plus_logo_web_2.png"
            }
        ]
    }
}

参数说明：

图片消息

消息示例：

{
    "touser": "UserID1|UserID2|UserID3",
    "toparty": " PartyID1 | PartyID2 ",
    "totag": " TagID1 | TagID2 ",
    "msgtype": "image",
    "agentid": "1",
    "image": {
        "content": "A+QIGv8u3c6YCCiiggAIKKKCAAgoooIACCiiggAIKKKCAAgoooIACCiiggAIKKKCAAgoooIACCiiggAIKKFAjAv8L0+vxkA8rL2IAAAAASUVORK5CYII="
    }
}

参数说明：

多格式消息

消息示例

{
    "touser": "UserID1|UserID2|UserID3",
    "toparty": " PartyID1 | PartyID2 ",
    "totag": " TagID1 | TagID2 ",
    "msgtype": "richtext",
    "agentid": "1",
    "richtext": {
        "content": [
            {
                "type": "text",
                "text": "阿斯顿发斯蒂芬"
            },
            {
                "type": "a",
                "href": "event:manual",
                "label": "百度"
            }
        ]
    }
}

参数说明：

Markdown

消息示例

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "md",
   "agentid": "1",
   "md": {
       "content": "# markdown示例 \n## 标题2  \n* 列表1 \n![alt](https://www.baidu.com/img/baidu_jgylogo3.gif)"
   }
}

参数说明：

Markdown支持如下语法子集：

1.标题：1-6级标题，# 号和文本之间要有一个空格

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

2.粗体：

**加粗文本**

3.斜体：

*斜体文本*

4.引用：

 >引用文本

5.字体颜色：只支持以下三种内置颜色

<font color="green">绿色</font>
<font color="gray">灰色</font>
<font color="red">红色</font>

6.链接

1. [百度一下]（https://www.baidu.com/）
2. https://www.baidu.com/

7.有序列表：1. 和文本之间要加一个空格

1. 有序列表
2. 有序列表
3. 有序列表

8.无序列表：- 和文本之间要加一个空格

- 无序列表
- 无序列表

9.行内代码

`code`

文件消息

消息示例：

{
    "touser": "UserID1|UserID2|UserID3",
    "toparty": " PartyID1 | PartyID2 ",
    "totag": " TagID1 | TagID2 ",
    "msgtype": "file",
    "agentid": "1",
    "file": {
       "md5": "a6f7b6a9b5e821d674a8590764715df4",
       "filename": "设计文档.txt"
    }
}

参数说明：

参数	类型	参数位置	是否必须	说明
touser	String	RequestBody	否	成员ID列表 消息接收者，多个接收者用竖线分隔，最多支持1000个 touser、toparty、totag三者不能全空
toparty	String	RequestBody	否	部门ID列表 消息接收者，多个接收者用竖线分隔，最多支持100个 当touser为@all时忽略本参数 touser、toparty、totag三者不能全空
totag	String	RequestBody	否	标签ID列表 消息接收者，多个接收者用竖线分隔 当touser为@all时忽略本参数 touser、toparty、totag三者不能全空
msgtype	String	RequestBody	是	image，固定值
agentid	String	RequestBody	是	应用ID 整型，管理后台应用详情页面获取
filename	String	RequestBody	是	附件名称，注：带文件格式后缀的完整文件名
md5	String	RequestBody	是	素材文件上传接口 返回的md5值

接收消息和事件

为了能够让企业应用和用户进行双向通信，管理员可以在应用的开发信息中设置回调配置，设置回调配置成功后，如果应用主动给用户发过消息，则用户也可以在会话框中向应用发消息，如流平台会将用户发送的消息转发至应用的接收消息服务器URL，同时也会定义各种事件向此URL发送通知。

设置接收服务器

管理员可以在应用中设置回调配置

验证URL有效性

当点击“保存”提交以上信息时，Hi平台会发送一条POST验证消息到填写的回调URL上，</br> 接收消息的服务器接收到验证请求后，需要作出正确的响应才能通过URL验证。</br> 校验通过后你的服务才可以正常接收机器人收到的消息。</br> 假设回调URL为https://example.com </br>企业平台会使用以下参数发送请求到回调地址。

请求地址：https://example.com

请求body：signature=5d03603ea6f77b5608d5735a914b3221&timestamp=1543647265&rn=376117246&echostr=7cff9

参数说明：

接收消息服务器URL收到请求后，需要做如下操作：

1. 通过参数signature对请求进行校验，确认调用者的合法性。详见附录
2. 在3秒内响应请求，响应内容为上一步得到的echostr值

URL有效性验证通过后，即可正常接收用户发给应用的消息。

服务号接收消息和事件

请求方式：POST（HTTPS）

请求地址：https://example.com/?signature=5d03603ea6f77b5608d5735a914b3221&timestamp=1543647265&rn=376117246

请求body：

message=xml_string&messageJson=json_string

xml_string格式：

<xml>
    <ToUserName><![CDATA[corpId]></ToUserName>
    <AgentID><![CDATA[agentId]]></AgentID>
    <Encrypt><![CDATA[msgEncrypt]]></Encrypt>
</xml>

json_string格式：

{
    "ToUserName": "corpId",
    "AgentID": "agentId",
    "Encrypt": "msgEncrypt，解密后为xml对应的json格式"
}

参数说明：

消息明文经过AES加密后的值Base64_Encode(AES_Encrypt[msg])，msg为消息内容明文，解密方式见附录

接收消息服务器URL收到请求后，需要做如下操作：

1. 可通过参数signature对请求进行校验，确认调用者的合法性。详见附录
   
2. 解密Encrypt参数得到消息内容，详见附录
   
3. 开发者需要及时响应http status 200，服务器在五秒内收不到响应会断掉连接
   

服务号消息和事件格式

文本消息

消息示例：

<xml>
    <FromUserId><![CDATA[UserId]]></FromUserId>
    <FromUserName><![CDATA[UserName]]></FromUserName>
    <CreateTime>1542780295</CreateTime>
    <MsgType>text</MsgType>
    <Content><![CDATA[text]]></Content>
</xml>

参数说明：

图片消息

消息示例：

<xml>
    <FromUserId><![CDATA[UserId]]></FromUserId>
    <FromUserName><![CDATA[UserName]]></FromUserName>
    <CreateTime>1542780295</CreateTime>
    <MsgType>image</MsgType>
    <PicUrl><![CDATA[this is a url]]></PicUrl>
<xml>

参数说明：

语音消息

消息示例：

<xml>
    <FromUserId><![CDATA[UserId]]></FromUserId>
    <FromUserName><![CDATA[UserName]]></FromUserName>
    <CreateTime>1542780295</CreateTime>
    <MsgType>voice</MsgType>
    <VoiceUrl><![CDATA[this is a url]]></PicUrl>
<xml>

参数说明：

关注/取消事件

事件示例：

   <xml>
        <FromUserId><![CDATA[UserId]]></FromUserId>
        <FromUserName><![CDATA[fromUser]]></FromUserName>
        <CreateTime></CreateTime>
        <MsgType>event</MsgType>
        <Event><![CDATA[subscribe]]></Event>
   <xml>

参数说明：