Push API v4 | WebPush 開發者指南 REST API 繁體中文

嚮某單個設備或者某設備列表推播一條通知、或者訊息。

推播的內容隻能是 JSON 表示的一個推播對象。

這是 Push API 最近的版本。v4 版本的改進為：

使用 HTTP Basic Authentication 的方式做訪問授權。這樣整個 API 請求可以使用常見的 HTTP 工具來完成，比如：curl，瀏覽器插件等。
推播內容完全使用 JSON 的格式。

請求頻率限制

我們的API對呼叫頻率有限制，以確保服務的穩定性和公平性。每個AppKey的QPS（每秒查詢量）限制如下：

標準限制：每秒最多500次請求。
高級限制：如果您是我們的付費計劃用戶，且您的付費AppKey需要更高的QPS限制，請聯繫我們的商務團隊：Sales@engagelab.com。

調用驗證

詳情參見 REST API 概述的鑒權方式說明。

調用地址

POST v4/push

              
              POST v4/push

此代碼塊在浮窗中顯示

請求示例

請求頭

> POST /v4/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

此代碼塊在浮窗中顯示

請求體

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

此代碼塊在浮窗中顯示

請求參數

推送的參數結構體，詳見下表：

關鍵字	類型	選項	含義
from	String	可選	當前業務傳送方
to	String 或 JSON Object	必填	傳送目標
body	JSON Object	必填	傳送請求體
platform	String 或 JSON Array	必填	推播平台
notification	JSON Object	可選	通知內容體，是被推播到客戶端的內容。與 message 一起二者必須有其一，二者不可以並存。
message	JSON Object	可選	訊息內容體，是被推播到客戶端的內容。與 notification 一起二者必須有其一，二者不可以並存。
options	JSON Object	可選	推播參數
request_id	String	可選	客戶自訂的可選字段，客戶用來標識是哪條請求，回響時返回。
custom_args	JSON Object	可選	客戶自訂的可選字段，回調時返回給客戶。

from

當前業務傳送方，String 類型，可選字段。

請求示例

{ "from":"push" }

              
              {
    "from":"push"
}

此代碼塊在浮窗中顯示

to

推播設備對象，表示一條推播可以被推播到哪些設備列表。確認推播設備對象，MTPush 提供了兩種方式，分別是註冊 ID 和廣播。

推播目標

關鍵字	類型	含義	說明	備註
all	String	發廣播	給全部設備進行推播	推播目標為 30 天內活躍過的設備。
registration_id	JSON Array	註冊 ID	數組。多個註冊 ID 之間是 OR 關係，即取並集。	設備標識。一次推播最多 1000 個。
tag	JSON Array	標簽	數組。多個標簽之間是 OR 的關系，即取並集。	用標簽來進行大規模的設備屬性、用戶屬性分群。一次推播最多 20 個。有效的 tag 組成：字母（區分大小寫）、數字、下劃線、漢字。限製：每一個 tag 的長度限製為 40 字節。（判斷長度需采用UTF-8編碼）
tag_and	JSON Array	標簽AND	數組。多個標簽之間是 AND 關系，即取交集。	註意與 tag 區分，一次推播最多 20 個。
tag_not	JSON Array	標簽NOT	數組。多個標簽之間，先取多標簽的並集，再對該結果取補集。	一次推播最多 20 個。
alias	JSON Array	別名	數組。多個別名之間是 OR 關系，即取並集。	用別名來標識一個用戶。一個設備只能綁定一個別名，但多個設備可以綁定同一個別名。一次推播最多 1000 個。有效的 alias 組成：字母（區分大小寫）、數字、下劃線、漢字。限製：每一個 alias 的長度限製為 40 字節。（判斷長度需采用UTF-8編碼）

數組裏多個值之間隱含的關系是是 OR，即取並集;但 tag_and 不同，其數組裏多個值之間是 AND 關系，即取交集。

tag_not若單獨使用，則我們會在廣播用戶中做tag_not處理。

這幾種類型可以並存。並存時多項的隱含關系是 AND，即取交集。例如：

"to" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }

先計算 "tag" 字段的結果 tag1 或 tag2 = A;

再計算 "tag_and" 字段的結果 tag3 且 tag4 = B;

再計算 "tag_not" 字段的結果 非 (tag5 或 tag6) = C;

"to" 的最終結果為 A 且 B 且 C 。

#### 請求示例

推播給全部（廣播）：

{ "to": "all", }

              
              {
  "to": "all",
}

此代碼塊在浮窗中顯示

推播給多個註冊 ID：

{ "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }

              
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

此代碼塊在浮窗中顯示

body

傳送請求體。支持的字段如下：

關鍵字	類型	選項	含義
platform	String 或 JSON Array	必填	推播平台
notification	JSON Object	可選	通知內容體，是被推播到客戶端的內容。與 message 一起二者必須有其一，二者不可以並存。
options	JSON Object	可選	推播參數

platform

MTPush 當前僅支持 Web 平台的推播，所以 platform 指定的關鍵字為："web"。

{ "platform" : "web" }

              
              { "platform" : "web" }

此代碼塊在浮窗中顯示

notification

“通知”對象，是一條推播的實體內容對象之一（另一個是“訊息”），是會作為“通知”推播到 web 端的。

關鍵字	類型	選項	含義	說明
web	JSON Object	必填	平台屬性	平台推播參數

web

Web 平台上的通知。

關鍵字	類型	選項	含義	說明
alert	String 或 JSON Object	必填	內容	訊息內容本身，這裏指定了，將會覆蓋上級統一指定的 alert 信息。
url	String	必填	web 推播 url	通知點選跳轉地址
title	String	可選	標題	訊息標題
extras	JSON Object	可選	擴展字段	這裏自訂 JSON 格式的 Key / Value 信息，以供業務使用。
icon	String	可選	通知 icon	建議 192*192px，不強制限制；強制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Firefox（Safari 和 Edge 系統默認無法自訂）
image	String	可選	通知大圖	建議 360*180px，不強制限制；強制限制大小上限 1M，限制格式：JPG、PNG、GIF，支持 Chrome、Edge（Firefox 和 Safari 不支持）

{ "notification": { "web": { "alert": "hello, Push!", "title": "Push Test", "url":"http://www.google.com", "icon":"", "image":"", "extras": { "news_id": 134, "my_key": "a value" } } } }

              
              {
    "notification": {
        "web": {
            "alert": "hello, Push!",
            "title": "Push Test",
            "url":"http://www.google.com",
            "icon":"",
            "image":"",
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代碼塊在浮窗中顯示

message

應用程式內訊息。或者稱作：自訂訊息，透傳訊息。

此部分內容不會展示在瀏覽器上，SDK 收到訊息內容後透傳給 Web，Web 自行處理業務邏輯。

訊息包含如下字段：

關鍵字	類型	選項	含義
msg_content	String 或 JSON Object	必填	訊息內容本身
title	String	可選	訊息標題
content_type	String	可選	訊息內容類型
extras	JSON Object	可選	JSON 格式的可選參數

示例：

{ "message": { "msg_content": "Hi,Push", "content_type": "text", "title": "msg", "extras": { "key": "value" } } }

              
              {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

此代碼塊在浮窗中顯示

options

推播可選項。當前包含如下幾個可選項：

關鍵字	類型	選項	含義	說明
time_to_live	Int 或 String	可選	離線消息保留時長(秒)	若推送時用戶不在線，可為該用戶保留指定時長的離線消息，以便其上線時再次推送。默認 86400 （1 天），最長 15 天，若系統瀏覽器支持的最大值 < 傳遞的有效值，則以系統最大值為準。設置為 0 表示不保留離線消息，只有推送當前在線的用戶可以收到。
override_msg_id	Long	可選	要覆蓋的消息 ID	如果當前的推送要覆蓋之前的一條推送，這裡填寫前一條推送的 msg_id 就會產生覆蓋效果，即：該 msg_id 離線收到的消息是覆蓋後的內容，即使該 msg_id web端用戶已經收到，如果通知欄還未清除，則新的消息內容會覆蓋之前這條通知。覆蓋功能起作用的時限是：1 天，如果在覆蓋指定時限內該 msg_id 不存在，則返回 1003 錯誤，提示不是一次有效的消息覆蓋操作，當前的消息不會被推送。
big_push_duration	Int	可選	定速推送時長(分鐘)	又名緩慢推送，把原本儘可能快的推送速度，降低下來，給定的 n 分鐘內，均勻地向這次推送的目標用戶推送；最大值為 1440。最多能同時存在 20 條定速推送。未設置則不是定速推送。
web_buttons	JSON Object	可選	在通知消息上添加buttons	最多添加2個button。可設置button名稱和跳轉連接，詳情查看web_buttons。
multi_language	json object	可選	多語言推送設置	推送內容多語言適配設置，詳情查看multi_language 說明。
third_party_channel	JSON Object	可選	Web 系統通道配置信息	僅針對配置了系統通道的用戶有效參數詳情查看 third_party_channel 說明。
plan_id	String	可選	推送計劃標識	需先創建計劃標識值,可在控制台創建或者通過API創建。
cid	String	可選	推送請求標識，用於防止重複推送	只允許字母、數字、下劃線和減號，長度不超過64個字符。注意相同AppKey下這個字段必須保持唯一性。

multi_language

本字段是 EngageLab Push 服務的多語言推送功能。它允許您為不同語言的用戶推送定制化的通知內容。通過在推送請求中指定多個語言及對應的消息內容、標題和 iOS 子標題，您可以針對用戶的語言設置發送適當的推送通知。

請求參數

關鍵字	類型	選項	含義	說明
en	string	可選	多語言key	對應推送用戶語言，key碼詳見附錄
content	string	可選	消息內容	根據用戶語言替換notification.web.alert、message.msg_content裡的數據
title	string	可選	消息標題	根據用戶語言替換notification.web.title、message.title裡的數據

請求示例

http請求方式: Post 請求地址：/v4/push POST數據格式:json POST數據例子: { "options": { "multi_language": { "en": { "content": "", "title": "", } } } }

              
                 http請求方式: Post
   請求地址：/v4/push
   POST數據格式:json
   POST數據例子:
   {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
        }
      }
    }
   }

此代碼塊在浮窗中顯示

返回示例

成功時： { } 失敗時： { "code":400, "data":"", "message":"錯誤資訊" }

              
              成功時：
{
   
}

失敗時：
{   
    "code":400,  
    "data":"",
  "message":"錯誤資訊"
}

此代碼塊在浮窗中顯示

web_buttons

使用web_buttons參數，描述按鈕的id、文本、圖標和url。參數描述如下：

關鍵字	類型	選項	含義	說明
id	必選	String	button id	chrom48+版本支持
text	必選	String	button 內容	chrom48+版本支持
icon	可選	String	button icon	chrom50+版本支持
url	必選	String	button 跳轉鏈接	chrom48+版本支持，若使用web_buttons,則web字段中的url不生效

調用示例如下：

[ { "id": "like-button", "text": "Like", "icon": "http://i.imgur.com/N8SN8ZS.png", "url": "https://yoursite.com" }, { "id": "read-more-button", "text": "Read more", "icon": "http://i.imgur.com/MIxJp1L.png", "url": "https://yoursite.com" } ]

              
              [
  {
    "id": "like-button",
    "text": "Like",
    "icon": "http://i.imgur.com/N8SN8ZS.png",
    "url": "https://yoursite.com"
  },
  {
    "id": "read-more-button",
    "text": "Read more",
    "icon": "http://i.imgur.com/MIxJp1L.png",
    "url": "https://yoursite.com"
  }
]

此代碼塊在浮窗中顯示

third_party_channel

本字段用來填寫 Web 係統通道的個性化信息，key 名稱為 w3push ，value 值為一個 Json Object 對象,該對象裏面僅包含一個可選的 distribution 字段，類型為 String

關鍵字	類型	選項	含義	說明
distribution	必選	String	Engagelab 和係統通道並存時，設定下發優先級	取值不能為空字符串。默認是first_ospush。 first_ospush：表示推播優先走係統通道下發，無效走 Engagelab 通道下發。 mtpush：表示推播強製走 Engagelab 通道下發。 secondary_push：表示推播優先走 Engagelab ，Engagelab 不在線再走係統通道，係統通道作為輔助（建議此種方式)。 ospush：表示推播強制僅走系統頻道下發。

調用示例如下：

{ "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

              
              {
  "third_party_channel":{
    "w3push":{
      "distribution":"mtpush"
    }
  }
}

此代碼塊在浮窗中顯示

request_id

請求 id，客戶自訂的可選字段。客戶用來標識是哪條請求，回響時返回。

請求示例

{ "request_id":"12345678" }

              
              {
      "request_id":"12345678"
}

此代碼塊在浮窗中顯示

返回示例

{ "msg_id": "1225764", "request_id": "12345678" }

              
              {
    "msg_id": "1225764",
    "request_id": "12345678"
}

此代碼塊在浮窗中顯示

custom_args

客戶自訂的，可選字段，回響時不返回，回調時返回。

{ "custom_args":"business info" }

              
              {
  "custom_args":"business info"
}

此代碼塊在浮窗中顯示

返回參數

成功返回

字段	類型	選項	描述
request_id	String	必選	響應屬性始終存在。請求時提交的自定義 ID 會原樣返回；請求未填寫時通常為空字符串。
message_id	String	必選	消息 ID，唯一標識某一條消息。

< HTTP/1.1 200 OK < Content-Type: application/json {"request_id":"18","msg_id":"1828256757"}

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

此代碼塊在浮窗中顯示

失敗返回

http 狀態碼為 4xx 或者 5xx，響應體包含字段如下：

字段	類型	選項	描述
code	int	必選	錯誤碼，詳見錯誤碼說明
message	String	必選	錯誤詳情

{ "code": 3002, "message": "Push.template field must be set correctly when type is template" }

              
              {
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
}

此代碼塊在浮窗中顯示

調用返回

HTTP 狀態碼

參考文檔：HTTP-Status-Code

錯誤碼

Code	描述	詳細解釋	HTTP Status Code
20101	推送參數無效	registration_id 無效或不屬於當前 appkey	400
21001	只支持 HTTP Post 方法	不支持 Get 方法	405
21002	缺少了必須的參數	必須改正	400
21003	參數值不合法	必須改正	400
21004	驗證失敗	必須改正，詳情請看：調用驗證	401
21005	消息體太大	必須改正，Notification/Message長度限制為 4000 字節	400
21007	輸入參數非法	receiver_value 參數非法	400
21008	app_key 參數非法	必須改正，請檢查所傳 appkey 是否為 24 位字串，是否多了空格	400
21009	系統內部錯誤	請聯繫技術支持團隊	400
21011	沒有滿足條件的推送目標	請檢查 to 字段	400
21015	請求參數校驗失敗	存在非預期的參數	400
21016	請求參數校驗失敗	參數類型錯誤，或者參數長度超出限制	400
21030	內部服務超時	稍後重試	503
21036	參數錯誤	通知消息和自訂訊息不能同時推送	400
21037	group_key 無效	group_key 不是 24 位字串或對應應用組不存在	400
21038	推送權限錯誤	VIP 已過期或未開通	400
21039	Web Button 參數錯誤	Web Button 的 id、url 或 text 為空	400
21040	Web Button 數量超限	Web Button 數量不能超過 2 個	400
21041	Web Button URL 無效	Web Button 的 url 格式無效	400
21042	Web Button ID 重複	同一請求中的 Web Button id 不能重複	400
21043	推送權限錯誤	應用存在待補繳帳單	400
21061	內容或回調配置校驗失敗	推送內容包含敏感詞，或請求的 callback_url 未配置在當前應用的回調地址中	400
21062	檔案推送目標數量超限	檔案中的推送目標數量超過應用配額或系統上限	400
23006	參數錯誤	定速推送 big_push_duration 超過最大值 1440	400
23008	接口限速	單應用推送接口 qps 達到上限(500 qps)	400
23009	推送權限錯誤	當前推送ip地址不在應用ip白名單內	400
27000	系統內存錯誤	請重试
27001	鑑權資訊無效	Basic Auth 中的 AppKey 長度合法但應用不存在，或應用基礎鑑權資訊無效	401
27006	override_msg_id 不存在	未查詢到 override_msg_id 對應的推送記錄	400
27007	override_msg_id 格式錯誤	override_msg_id 為負數或格式無效	400
27008	参数错误	third_party_channel 里面的 distribution 不为空，但是 notification 的 alert 内容为空	401
27009	参数错误	third_party_channel 中 distribution 格式无效或为空	401
27104	分群 ID 不存在	segment ID 不存在，請先建立或修改分群	400
27200	msg_id 無效	msg_id 格式無效	400
27201	msg_id 不存在或不屬於應用	msg_id 不存在，或不屬於當前 appkey	400
27202	訊息已撤回	msg_id 對應訊息已經執行過撤回操作	400
27203	系統錯誤	系統錯誤，請重試	400
27204	訊息撤回時間超限	訊息已超過允許撤回的時間	400
27300	推播計劃 ID 無效	plan_id 格式無效	400
27301	推播計劃描述無效	plan_description 長度超過限制	400
27302	推播計劃數量超限	可用推播計劃數量已達上限	400
27303	推播計劃 ID 為空	plan_id 不能為空	400
27304	推播計劃 ID 過長	plan_id 長度超過限制	400
27305	推播計劃不存在	當前 appkey 下不存在所傳 plan_id	400
27306	推播計劃 ID 數量超限	plan_id 數量超過限制	400
28100	定時任務參數無效	schedule task 參數無效	400
28101	定時任務鑑權失敗	Basic Authentication 失敗	401
28102	定時推播參數無效	push 參數為空或無效	400
28103	定時推播時間無效	single time 或 trigger time 格式錯誤	400
28104	定時任務不存在	請求操作的 schedule task 不存在	404
28105	定時任務沒有推播目標	對應定時時間沒有滿足條件的推播目標	400
28200	定時任務系統錯誤	服務內部發生未預期錯誤	500

推播限製

係統通道	標題長度	內容長度	其他說明
Engagelab 通道	不限製，但限製訊息體總大小	不限製，但限製訊息體總大小	MTPush 中 Notification 長度限製為 4000 個字節。
係統通道	＜ 20 個字符（40 個英文字符）	通知中心和鎖屏狀態最多顯示 110 個字符，55 個漢字。頂部彈窗最多顯示 62 個字符，31 個漢字，超過部分會顯示省略號。	暫無

多語言碼

語言名稱	語言代碼
英語	en
阿拉伯語	ar
中文（簡體）	zh-Hans
中文（繁體）	zh-Hant
捷克語	cs
丹麥語	da
荷蘭語	nl
法語	fr
德語	de
印地語	hi
義大利語	it
日語	ja
韓語	ko
馬來語	ms
俄語	ru
西班牙語	es
泰語	th
越南語	vi
印度尼西亞語	id
挪威語	no
瑞典語	sv
波蘭語	pl
土耳其語	tr
希伯來語	he
葡萄牙語	pt
羅馬尼亞語	ro
匈牙利語	hu
芬蘭語	fi
希臘語	el
烏克蘭語	uk
老撾語	lo
葡萄牙語（葡萄牙）	pt_PT
葡萄牙語（巴西）	pt_BR
西班牙語（阿根廷）	es_AR
西班牙語（西班牙）	es_ES
西班牙語（拉丁美洲）	es_419