1. Rest API 概述（V2）

信鸽推送提供遵从 REST 规范的 HTTP API，以供开发者远程调用信鸽提供的服务。接口主要分为四大类：

• Push API，包含多种消息推送的接口
• 标签 API， 主要完成标签的新增、删除、查询
• 账号 API，主要完成账号的查询、删除
• 工具类 API，用来定位问题和其他数据查询

1.1. 请求方式

支持GET；

支持POST，但要求HTTP HEADER中"Content-type"字段要设置为"application/x-www-form-urlencoded"

1.2. 协议描述

请求URL： http://openapi.xg.qq.com/v2/class_path/method?params

1.3. 通用基础参数

通用基础参数是指，在各个接口请求URL结构中的params字段都需要包含(基础)的参数

具体如下表：

1.4. 鉴权方式

计算公式：Sign=MD5(http_methodURIK1=V1…Kn=Vnsecret_key);（注意：参数必须按照此顺序放置）

例如：

单推接口调用：

POST请求 http://openapi.xg.qq.com/v2/push/single_device

参数列表：

access_id=123，timestamp=1386691200，Param1=Value1，Param2=Value2，secret_key=abcde，

根据上述公式得出：

sign=MD5(POSTopenapi.xg.qq.com/v2/push/single_deviceaccess_id=123Param1=Value1Param2=Value2timestamp=1386691200abcde)

得出，

sign=6b90c7f4a137c7d0b756d48f748c93b2

1.5. 通用基础返回值

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

{ 
    "ret_code":0, 
    "err_msg":"",
    "result":{"":""} 
}

具体描述见下表：

1.6. API限制

1. 除去全量推送接口有调用频率的限制外，其他均无此限制
2. 推送的消息体大小限制为4K，此限制适用于Push API中的message字段
3. 标签群推限制标签数量最多是50个

1.7. Push API

1.7.1. Push API基础参数

推送接口的基础参数是指，所有推送消息的接口的通用参数，切记接口调用参数中必须还要包含通用基础参数

具体通用参数见下表：

1.7.2. 全量推送

此接口用于对全部设备推送消息，后台对本接口的调用频率有限制:

• 1小时内不能推相同内容的消息；

• 1小时内最多调用此接口30次

请求URL:

http://openapi.xg.qq.com/v2/push/all_device?params

请求参数：

通用基础参数和Push API 基础参数

响应结果：

用基础返回值，result字段会包含给app下发的任务id:

{
    "push_id":10000
}

如果是循环任务，返回全部任务的id

具体示例如下：

{
    "push_id":10000,//父任务id
    "sub_push_ids":[234,235,236] //子任务id
}

1.7.3. 群推送

群推送是指，根据标签、账号、设备(Token)进行群组推送

标签群推

可以针对设置过标签的设备进行推送。如：性别、身份等

请求URL:

http://openapi.xg.qq.com/v2/push/tags_device?params

请求参数：

除了通用基础参数和Push API 基础参数，还包括如下特定参数：

响应结果：

用基础返回值，result字段会包含给app下发的任务id

{
    "push_id":10000
}

如果是循环任务，返回全部任务的id

具体示例如下：

{
    "push_id":10000,//父任务id
    "sub_push_ids":[234,235,236] //子任务id
}

帐号群推

账号群推是指，对通过客户端SDK绑定接口绑定的账号的群组推送，iOS和Android的SDK都提供相应的接口。

请求URL：

http://openapi.xg.qq.com/v2/push/account_list?params

请求参数：

除了通用基础参数 和 Push API 基础参数，还包括如下特定参数：

响应结果：

用基础返回值，result字段的JSON为每个account发送返回码

超大批量账号群推

如果推送目标帐号数量很大（比如>100），推荐使用此方法，分为以下两步：

(1)第一步，创建推送消息：

请求URL:

http://openapi.xg.qq.com/v2/push/create_multipush?params

请求参数：

通用基础参数 和 Push API 基础参数

响应结果：

用基础返回值，其中result字段的JSON包含消息标识，举例如下：

{
"push_id":100000
}

(2)第二步，使用超大批量推送接口进行消息推送

请求URL:

http://openapi.xg.qq.com/v2/push/account_list_multiple?params

请求参数：

除通用基础参数外，还包括如下参数：

响应结果：

用基础返回值

设备群推

设备群推是指，使用设备标识(Device Token)进行消息的推送

使用此接口需要2步：

（1）第一步，创建消息

请求URL:

http://openapi.xg.qq.com/v2/push/create_multipush?params

请求参数：

通用基础参数 和 Push API 基础参数

响应结果：

用基础返回值，其中result字段的JSON包含消息标识，举例如下：

{
"push_id":100000
}

（2）第二步，调用推送接口

请求URL:

http://openapi.xg.qq.com/v2/push/device_list_multiple?params

请求参数：

除了通用基础参数 ，还包括如下特定参数：

响应结果：

用基础返回值

1.7.4. 单推

单推，指定账号，设备标识（Device Token）进行推送

账号单推

账号单推是指，对通过客户端SDK绑定接口绑定的指定单个账号的推送，iOS和Android的SDK都提供相应的接口。

请求URL:

http://openapi.xg.qq.com/v2/push/single_account?params

请求参数：

除了通用基础参数 和 Push API 基础参数，还包括如下特定参数：

响应结果：

用基础返回值

设备单推

设备单推是指，使用指定的一个设备标识(Device Token)进行消息的推送，关于设备标识的获取，客户端SDK有相应的接口

请求URL：

http://openapi.xg.qq.com/v2/push/single_device?params

请求参数：

除了通用基础参数 和 Push API 基础参数，还包括如下特定参数：

响应结果：

用基础返回值

1.7.5. 消息体格式

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

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

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

Android普通消息

Android平台具体字段如下表：

完整的消息示例如下：

{
    "title ":"xxx",
    "content ":"xxxxxxxxx",
    "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",
    "custom_content":{
        "key1":"value1",
        "key2":"value2"
    },
    "action":{
        "action_type":1,// 动作类型，1，打开activity或app本身；2，打开浏览器；3，打开Intent
        "activity":"MyActivityClassName"
        "aty_attr":{ // activity属性，只针对action_type=1的情况
            "if":0,  // Intent的Flag属性
            "pf":0   // PendingIntent的Flag属性
        },
        "browser":{
            "url":"http://xg.qq.com", // 仅支持http、https
            "confirm":1   // 是否需要用户确认
        },
        "intent":"xgscheme://com.xg.push/notify_detail"// 客户端 Android SDK版本需要大于等于3.2.3，然后在客户端的intent配置data标签，并设置scheme属性
    },
    "accept_time":[//在下午1点到下午2点或者是凌晨0点到上午9点之间，消息可以展示，其他时间段，消息不会展示
        {
            "start":{
                "hour":"13",
                "min":"00"
            },
            "end":{
                "hour":"14",
                "min":"00"
            }
        },
        {
            "start":{
                "hour":"00",
                "min":"00"
            },
            "end":{
                "hour":"09",
                "min":"00"
            }
        }
    ]
}

iOS 普通消息

iOS平台具体字段如下表：

完整的消息示例如下：

{
    "aps":{
        "alert":{
            "title":"this is a title",
            "body":"this is content"
        },
        "badge":1,
        "category":"CategoryID"
    },
    "custom":{
        "key":"value"
    }
}

Android透传消息

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

Android平台具体字段如下表：

具体完整示例：

{
    "title":"this is title",
    "content":"this is content",
    "custom_content":{
        "key1":"value1",
        "key2":"value2"
    },
    "accept_time":[//在下午1点到下午2点或者是凌晨0点到上午9点之间，消息可以展示，其他时间段，消息不会展示
        {
            "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来处理消息逻辑

具体字段如下表：

具体完整示例：

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

1.7.6. 查询消息状态

此接口目前仅支持全量推送和标签群推消息的发送状态的查询，不支持其他推送方式的查询

请求URL：

http://openapi.xg.qq.com/v2/push/get_msg_status?params

除了通用基础参数 ，还包括如下特定参数：

响应结果：

用基础返回值，其中result字段的JSON形式为：

{
    "Total": "1", 
    "list": {
        "0": {
            "Content": "test", //推送消息体
            "OfflineSave": "86400", //Android 离线保存时间
            "ScheduleSendTime": "2017-04-12 17:50:00", 
            "SendTime": "2017-04-12 17:50:01", //根据算法从tobe_sent_tome、creat_time\start_time中选择
            "TagsList": "", //标签时的标签列表
            "Title": "this is title", //推送标题
            "Type": "3", //任务类型：3-全推、4-标签推送
            "cleanup": "0", //清除
            "click": "0", //点击
            "create_time": "2017-04-12 17:49:01", //任务创建时间
            "push_active": "0", //Android最近30天活跃设备
            "push_id": "2511161036", 
            "push_online": "0", //实发
            "start_time": "2017-04-12 17:50:01", //任务开始推送时间
            "status": "2", //0-创建任务，1-推送中，2-推送完成，4-非法任务，3-推送失败，9-内容重复，10-频率控制，11-删除离线消息，12-用户取消推送
            "verify": "123", //展示
            "verify_svc":"0"//到达设备数量
            "cal_type": "0"
        }
    }
}

1.7.7. 取消推送

目前V2版本支持根据消息ID来取消尚未触发的、定时的、全量推送或标签群推的推送消息

请求URL：

http://openapi.xg.qq.com/v2/push/cancel_timing_task?params

请求参数：

除了通用基础参数 ，还包括如下特定参数：

响应结果：

用基础返回值，其中result字段的JSON形式为：

{
"status": 0 //0为成功，其余为失败
}

1.8. 标签(Tag)接口

标签接口主要是用来对标签进行查询、设置、删除操作

V2版本支持的具体接口如下：

1. 批量新增标签
2. 批量删除标签
3. 查询全部标签
4. 查询单个设备(根据Device Token)的标签
5. 查询单个标签的设备(Device Token)总数

批量新增标签

批量新增标签，可以给多定的设备(Device Token)设置标签，但是一个 App 下面最多只能有1万个标签，若超出，此接口将返回失败

请求URL:

http://openapi.xg.qq.com/v2/tags/batch_set

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值

批量删除标签

请求URL:

http://openapi.xg.qq.com/v2/tags/batch_del

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值

查询全部标签

此接口用来查询当前指定应用下被设置的全部标签数量和对应的标签名

请求URL:

http://openapi.xg.qq.com/v2/tags/query_app_tags?params

请求参数：

除了通用基础参数，还可以包括如下特定参数：

响应结果：

用基础返回值中，result字段的JSON格式如下：

{
"total": 2, //指定应用的总tag数
"tags":["tag1","tag2"] //依据limit参数查询出的标签数组
}

查询单个指定设备的标签

此接口根据设备标识(Device Token)来查询相应设备被设置的全部标签，请务必保证设备标识（Device Token）的合法性

请求URL:

http://openapi.xg.qq.com/v2/tags/query_token_tags?params

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

在用基础返回值参数中，result字段的JSON格式如下：

{
"tags":["tag1","tag2"]
}

查询单个指定标签的Token总数

请求URL:

http://openapi.xg.qq.com/v2/tags/query_tag_token_num?params

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值中，result字段的JSON格式如下：

{
"device_num":100000
}

1.9. 账号(Account)接口

账号接口主要是用来查询、删除终端设备Token关联的账号

V2版本支持的具体接口如下：

1. 查询单个账号关联的设备(Device Token)
2. 删除单个账号关联的设备(Device Token)
3. 删除账号关联的全部设备(Device Token)

查询单个账号关联的设备（暂可不用）

请求URL:

http://openapi.xg.qq.com/v2/application/get_app_account_tokens?params

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值中，result字段的JSON格式如下：

{
"tokens":["token1","token2"]
}

删除单个账号关联的单个设备Token

请求URL:

http://openapi.xg.qq.com/v2/application/del_app_account_tokens?params

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值中，result字段的JSON格式如下：

{
"tokens":["token1"]
}

注意：tokens字段对应的值表示当前账号目前仍关联的设备标识

删除单个账号关联的全部设备Token

请求URL:

http://openapi.xg.qq.com/v2/application/del_app_account_all_tokens?params

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值

1.10. 工具类接口

1.10.1. 查询应用覆盖的设备Token总数

此接口用来查询指定应用的全部已注册的设备标识(Device Token)的总数

请求URL:

http://openapi.xg.qq.com/v2/application/get_app_device_num?params

请求参数：

通用基础参数

响应结果：

用基础返回值，其中result字段的JSON形式为：

{
"device_num": 34567
}

1.10.2. 查询指定设备Token的注册状态

此接口是为了查询指定设备(Device Token)在信鸽服务器上注册的状态，设备能收到信鸽推送的消息的首要条件是设备(Device Token)已经被注册到信鸽的后台，否则信鸽无法给指定设备下发消息的

请求URL:

http://openapi.xg.qq.com/v2/application/get_app_token_info?params

请求参数：

除了通用基础参数，还包括如下特定参数：

响应结果：

用基础返回值，其中result字段的JSON形式为：

{
"isReg":1,//（1为token已注册，0为未注册）
"connTimestamp":1426493097, //（最新活跃时间戳）
"msgsNum":2 //（该应用的离线消息数）
}

1.11. 返回码一览

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