消息推送开发指南

部署在WorkPlus平台应用中心中的各种应用——包括轻应用、iOS和Android原生应用——可以通过WorkPlus平台向用户发送包括文本和图文在内的各种消息。

本文具体描述消息发送请求和响应的详细格式。

1. 支持的消息类型

WorkPlus支持下列的消息类型：

• 文本消息TEXT
• 图片消息IMAGE
• 语音消息VOICE
• 文件消息FILE
• 图文消息ARTICLE

2. 消息推送API

WorkPlus通过REST向外界暴露API。发送所有类型消息的API都是下面这个：

POST https://api.workplus.io/app/mbox?access_token={access_token}

（如果您的WorkPlus是私有化部署，请根据实际情况修改API服务器的域名/IP和端口）

请把{access_token}替换为你的应用登录WorkPlus后获得的access_token。获取access_token的方法请参考应用快速接入与单点登录指南。

3. HTTP HEADER设置

WorkPlus RESTful API的请求和响应的媒体类型都是JSON。因此，发送消息时必须设置以下的HTTP HEADER：

Content-Type="application/json"

4. 请求参数

请求参数是个JSON对象，下面是个文本消息请求参数的例子，要将文本消息“你好！”推送给名为"zhangsan", "lisi"的两个用户：

{
    "type": "TEXT",
    "body": {
        "content": "你好！"
        "dest_type": "P2P"
    },
    "client_ids": ["zhangsan", "lisi"]
}

每种消息类型都包含type、body和client_ids三个属性。

不同的消息type具有不同的body结构（下文会详细介绍）。

各种消息请求的body对象中都有个必填的dest_type属性，其取值范围只有P2P和DISCUSSION。当dest_type=P2P时，消息发送给个人（client_ids是用户名的列表）；当dest_type=DISCUSSION时，消息发送给群组（client_ids是群组名称的列表）。

4.1 文本消息TEXT

范例：

{
    "type": "TEXT",
    "body": {
        "content": "你好！"
        "dest_type": "P2P"
    },
    "client_ids": ["zhangsan", "lisi"]
}

当请求对象的type="TEXT"时，body对象包含下列属性:

4.2 图片消息IMAGE

范例：

{
    "type" : "IMAGE",
    "body": {
        "media_id": "56722e6d83143c4999b45843",
        "content" : "/9j/4AAQSkZJRgABAQAASABIAAD/"
        "dest_type": "DISCUSSION"
    }
    "client_ids": ["dev"]
}

当请求对象的type="IMAGE"时，body对象包含下列属性:

4.3 语音消息VOICE

范例：

{
    "type": "VOICE",
    “body”: {
        "media_id": "56722ac083143c4999b4583f",
        "played": "YES",
        "duration": 2,
        "dest_type": "P2P"
    }
    "client_ids": ["zhangsan", "lisi"]
}

当请求对象的type="IMAGE"时，body对象包含下列属性:

4.4 文件消息FILE

范例：

{
    "type": "FILE",
    “body”: {
        "media_id": "5672706f83143c4999b45849",
        "name": "HTTP-RFC2616.pdf",
        "size" : 713185
        "dest_type": "P2P"
    }
    "client_ids": ["zhangsan", "lisi"]
}

当请求对象的type="FILE"时，body对象包含下列属性:

4.5 图文消息ARTICLE

范例：

{
    "type": "ARTICLE",
    "body": {
        "articles": 
            [
                {
                    "url" : "文章打开地址",
                    "show_cover" : true,
                    "cover_url" : "图文封面图片url",
                    "summary" : "文章摘要",
                    "create_time" : 1433314282603,
                    "content_source" : "文章原文链接",
                    "author" : "文章作者",
                    "sort" : 0,
                    "title" : "文章标题",
                    "content" : "<p>文章内容</p>"
                }
            ]
        "dest_type": "P2P"
    },
    "client_ids": ["zhangsan", "lisi"]
}

当请求对象的type="ARTICLE"时，body对象包含单一属性articles，它本身是一个JSON数组，包含一个或多个JSON对象，这些该对象有下列的属性:

5. 响应格式

消息推送的响应同样是个JSON对象。

5.1 成功响应

成功响应的范例：

{
    "status": 0,
    "message": "Everything is ok.",
    "result": {
        "id": "推送计划ID",
        "app_id": "应用id",
        "tenant_id": "租户id",
        "material_id": "",
        "expects": "",
        "fails": "",
        "oks": "",
        "create_time": "创建时间",
        "refresh_time": "刷新时间",
        "expect_time": ""
    }
}

说明：

result对象的属性说明如下：

5.2 失败响应

失败响应的范例：

{
    "status": 115,
    "message": "Internal Server Error.",
    "result": {
    }
}

属性说明同成功响应。不过status属性是非0整数。