1. Rest API 概述（V3）

1.1. API概述

信鸽推送提供遵从 REST 规范的 HTTP API，以供开发者远程调用信鸽提供的服务

接口主要分为四大类：

本文档将只描述接口状态为正常的 API，其他状态的 API，请使用 v2 版本

1.2. 请求方式

• 仅支持 HTTPs

• 仅支持 POST

1.3. 权鉴方式

• 采用基础鉴权的方式，HTTP Header（头）里加一个字段（ Key/Value 对）：

  Authorization: Basic base64_auth_string
  

• 其中 base64_auth_string 的生成算法为：base64(APPID:SECRETKEY)

  即对 APPID 加上冒号，加上 SECRETKEY 拼装起来的字符串，再做 base64 转换

• APPID 和 SECRET KEY 可在信鸽官网【我的应用】【应用配置】中获取

1.4. 协议描述

请求URL：https://openapi.xg.qq.com/v3/<class_path>/<method>

1.5. API限制

• 除去全量推送、标签推送接口有调用频率的限制外，其他均无限制

• 推送的消息体大小限制为 4K，此限制适用于 Push API 中的 message 字段

1.6. 通用基础返回值

• 通用基础返回值，是所有请求的响应中都会包含的字段，格式如下：

{
    "seq": 0,
    "push_id": 123,
    "ret_code": 0,
    "environment": "product",
    "err_msg": "",
    "result": {
        "": ""
    }
}

• 返回值字段描述表：

1.7. Push API

1.7.1. Push API 概述

• Push API 是所有推送接口的统称

• Push API 有多种推送目标，推送目标如下：

  • 全量推送

  • 标签推送

  • 单设备推送

  • 设备列表推送

  • 单账号推送

  • 账号列表推送

• 所有推送目标都采用相同的 URL 发起请求，URL：https://openapi.xg.qq.com/v3/push/app

• 所有请求参数通过 JSON 封装上传给后台，后台通过请求参数区分不同的推送目标

1.7.2. Push API 必要参数

推送必要参数指一条推送消息必需携带的参数

audience_type：推送目标

推送目标，表示一条推送可以被推送到哪些设备

Push API 提供了多种推送目标的，比如：全量、标签、单设备、设备列表、单账号、账号列表

• 全量推送：推送给全部设备

  {
    "audience_type": "all"
  }
  

• 标签推送：推送给同时设置了"tag1"和”tag2“标签的设备

  {
    "audience_type": "tag",
    "tag_list": {
        "tags": [
            "tag1",
            "tag2"
        ],
        "op": "AND"
    }
  }
  

• 单设备推送：推送给token为"token1"的设备

  {
    "audience_type": "token",
    "token_list": [
        "token1"
    ]
  }
  

• 设备列表推送，推送给token为"token1"和"token2"的设备

  {
    "audience_type": "token_list",
    "token_list": [
        "token1",
        "token2"
    ],
    "push_id": "0"
  }
  

• 单账号推送：推送给账号为"account1"的设备

  {
    "audience_type": "account",
    "account_list": [
        "account1"
    ]
  }
  

• 账号列表推送：推送账号为"account1"和"account2"的设备

  {
    "audience_type": "account_list",
    "account_list": [
        "account1",
        "account2"
    ],
    "push_id": "0"
  }
  

platform：推送平台

当前支持 Android、iOS 两个平台的推送

其关键字分别为："android", "ios"，如果要同时推送两个平台，则关键字为："all"

• 推送到所有平台：

  {
    "platform": "all"
  }
  

• 推送到安卓平台：

  {
    "platform": "android"
  }
  

• 推送到iOS平台：

  {
    "platform": "ios"
  }
  

message_type：消息体类型

针对不同平台，消息类型稍有不同，具体参照下表：

message：消息体

消息体，即下发到客户端的消息

Push API 对 iOS 和 Android 两个平台的消息有不同处理，需要分开来实现对应平台的推送消息，推送的消息体是 JSON 格式

Android普通消息

Android平台具体字段如下表：

完整的消息示例如下：

{
    "title": "xxx",
    "content": "xxxxxxxxx",
    "accept_time": [
        {
            "start": {
                "hour": "13",
                "min": "00"
            },
            "end": {
                "hour": "14",
                "min": "00"
            }
        },
        {
            "start": {
                "hour": "00",
                "min": "00"
            },
            "end": {
                "hour": "09",
                "min": "00"
            }
        }
    ],
    "android": {
        "n_id": 0,
        "builder_id": 0,
        "ring": 1,
        "ring_raw": "ring",
        "vibrate": 1,
        "lights": 1,
        "clearable": 1,
        "icon_type": 0,
        "icon_res": "xg",
        "style_id": 1,
        "small_icon": "xg",
        "action": {
            "action_type ": 1,
            "activity": "xxx",
            "aty_attr": {
                "if": 0,
                "pf": 0
            },
            "browser": {
                "url": "xxxx ",
                "confirm": 1
            },
            "intent": "xxx"
        },
        "custom_content": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

iOS普通消息

iOS平台具体字段如下表：

完整的消息示例如下：

{
    "title": "xxx",
    "content": "xxxxxxxxx",
    "ios":{
        "aps": {
            "alert": {
                "subtitle": "my subtitle"
            },
            "badge": 5,
            "category": "INVITE_CATEGORY"
        },
        "custom1": "bar",
        "custom2": [
            "bang",
            "whiz"
        ],
        "xg": "oops"
    }
}

Android透传消息

透传消息，Android平台特有，即不显示在手机通知栏中的消息，可以用来实现让用户无感知的向App下发带有控制性质的消息

Android平台具体字段如下表：

具体完整示例：

{
    "title": "this is title",
    "content": "this is content",
    "android": {
       "custom_content": {
          "key1": "value1",
          "key2": "value2"
             }
    },
    "accept_time": [
        {
            "start": {
                "hour": "13",
                "min": "00"
            },
            "end": {
                "hour": "14",
                "min": "00"
            }
        },
        {
            "start": {
                "hour": "00",
                "min": "00"
            },
            "end": {
                "hour": "09",
                "min": "00"
            }
        }
    ]
}

iOS静默消息

静默消息，iOS平台特有，类似Android中的透传消息，消息不展示，当静默消息到达终端时，iOS会在后台唤醒App一段时间(小于30s)，让App来处理消息逻辑

具体字段如下表：

具体完整示例：

{
    "ios":{
        "aps": {
            "content-available": 1
        },
        "custom": {
            "key1": "value1",
            "key2": "value2"
        },
        "xg": "oops"
    }
}

1.7.3. Push API 可选参数

Push API 可选参数是除了 audience_type、platform、message_type、message 以外，可选的高级参数

1.7.4. Push API 请求完整示例

标签推送请求消息

POST /v3/push/app HTTP/1.1
Host: openapi.xg.qq.com
Content-Type: application/json
Authorization: Basic YTViNWYwNzFmZjc3YTplYTUxMmViNzcwNGQ1ZmI1YTZhOTM3Y2FmYTcwZTc3MQ==
Cache-Control: no-cache
Postman-Token: 4b82a159-afdd-4f5c-b459-de978d845d2f
{
    "platform": "android",
    "audience_type": "tag",
    "tag_list": {
        "tags": [
            "tag1",
            "tag2"
        ],
        "op": "AND"
    },
    "message_type": "notify",
    "message": {
        "title": "this is title",
        "content": "this is content",
        "custom_content": {
            "key1": "value1",
            "key2": "value2"
        },
        "accept_time": [
            {
                "start": {
                    "hour": "13",
                    "min": "00"
                },
                "end": {
                    "hour": "14",
                    "min": "00"
                }
            }
        ]
    }
}

标签推送应答消息

{
    "seq": 0,
    "environment": "product",
    "ret_code": 0,
    "push_id": "3895624686"
}

1.8. 账号类型

账号类型是客户端调用SDK接口绑定，类型如下表所示：

1.9. 错误码

信鸽REST API接口较多，开发者使用过程中不可避难会遇到各种问题，这里提供了常见的错误码释义，对应着是通用基础返回值中的ret_code字段的可能值