管理应用

PDF版下载

消息推送

应用向成员推送消息

请求方式：POST（HTTPS）

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

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

参数说明：

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

返回结果：

{
    "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": "Title",
                "description": "Description",
                "url": "URL",
                "picurl": "PIC_URL"
            },
            {
                "title": "Title",
                "description": "Description",
                "url": "URL",
                "picurl": "PIC_URL"
            }
        ]
    }
}

参数说明：

图片消息

消息示例：

{
    "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"
    }
}

参数说明：

接收消息和事件

为了能够让第三方应用和用户进行双向通信，服务商可以在应用的开发信息中设置回调配置，设置回调配置成功后，如应用主动给用户发过消息，则用户可以在会话框中向应用发消息，如流平台会将用户发送的消息转发至应用的接收消息服务器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值之后接入验证生效，接收消息开启成功。

接收事件

请求方式：POST（HTTPS）

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

参数说明：

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

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

请求body：

事件明文经过AES加密后的值Base64_Encode(AES_Encrypt[msg])，msg为事件内容明文，解密方式见附录 msg明文示例：

{
    "eventtype": "CHANGE_AUTH",
    "suiteid": "tjATMNQPPASSWDR",
    "authcorpid": "hiTXaBQPMQTPM",
    "eventtime": 12121212121 //ms
}

接收事件协议的说明

1. 如流服务器在3秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。如果在调试中，发现无法收到响应的消息，可以检查是否消息处理超时。
2. 当接收成功后，http头部返回200表示接收ok，其他错误码会被判定失败并发起重试

接收服务号消息

请求方式：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，服务器在五秒内收不到响应会断掉连接

接收事件格式

授权通知事件

请求body：

{
    "eventtype": "CHANGE_AUTH",
    "suiteid": "tjATMNQPPASSWDR",
    "authcorpid": "hiTXaBQPMQTPM",
    "eventtime": 12121212121 //ms
}

参数说明：

成员通知事件

权限要求： 获得企业安装应用时的通讯录信息只读或读写授权 联系如流开通成员通知事件权限 请求body：

{
    "eventtype": "CONTACT_EE_ADD",
    "corpid": "tjATMNQPPASSWDR",
    "userid": "zhangsan",
    "time": 12121212121 //ms
}

参数说明：

部门通知事件

权限要求： 获得企业安装应用时的通讯录信息只读或读写授权 联系如流开通部门通知事件权限 请求body：

{
    "eventtype": "CONTACT_DEPT_ADD",
    "corpid": "tjATMNQPPASSWDR",
    "deptid": 1,
    "time": 12121212121 //ms
}

参数说明：

可见范围通知事件

权限要求： 企业安装应用时选择的可见范围发生变更时会下发该通知

部门 请求body：

{
    "eventtype": "AGENT_ALLOW_DEPARTMENT_ADD",
    "corpid": "tjATMNQPPASSWDR",
    "agentid": 1234
    "department": [
        {
            "id": 2,
            "name": "PARTYNAME",
            "parentid": 1
        }
    ],
    "time": 12121212121 //ms
}

参数说明：

标签 请求body：

{
    "eventtype": "AGENT_ALLOW_TAG_ADD",
    "corpid": "tjATMNQPPASSWDR",
    "agentid": 1234,
    "tag": [
        {
            "id": 2,
            "name": "tagName"
        }
    ],
    "time": 12121212121 //ms
}

参数说明：

成员 请求body：

{
    "eventtype": "AGENT_ALLOW_EMPLOYEE_ADD",
    "corpid": "tjATMNQPPASSWDR",
    "agentid": 1234,
    "user": [
        {
            "id": 2,
            "name": "tagName"
        }
    ],
    "time": 12121212121 //ms
}

参数说明：

接收服务号消息格式

文本消息

消息示例：

<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>

参数说明：