Push API v4

嚮某單個設備或者某設備列表推播一條通知、或者訊息。推播的內容隻能是 JSON 表示的一個推播對象。

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

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

調用驗證

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

調用地址

POST https://push.api.engagelab.cc/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": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } }, "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "message": { "msg_content": "Hi,MTPush", "content_type": "text", "title": "msg", "extras": { "key": "value" } }, "options": { "time_to_live": 60, "apns_production": false } }, "request_id": "12345678", "custom_args": "business info" }

          {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "all",
        "notification": {
            "android": {
                "alert": "Hi, Push!",
                "title": "Send to Android",
                "builder_id": 1,
                "extras": {
                    "newsid": 321
                }
            },
            "ios": {
                "alert": "Hi, MTPush!",
                "sound": "default",
                "badge": "+1",
                "extras": {
                    "newsid": 321
                }
            }
        },
        "message": {
            "msg_content": "Hi,MTPush",
            "content_type": "text",
            "title": "msg",
            "extras": {
                "key": "value"
            }
        },
        "options": {
            "time_to_live": 60,
            "apns_production": false
        }
    },
    "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 個。

請求示例

推播給全部（廣播）：

{ "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 一起二者必須有其一，二者不可以並存。
message	JSON Object	可選	訊息內容體，是被推播到客戶端的內容。與 notification 一起二者必須有其一，二者不可以並存。
options	JSON Object	可選	推播參數

platform

MTPush 當前支持 Android， iOS 平台的推播。其關鍵字分別為："android", "ios"。

如果目標平台為 iOS 平台，需要在 options 中通過 apns_production 字段來製定推播環境。True 表示推播生産環境，False 表示要推播開發環境；如果不指定則為推播生産環境。

推播到所有平台：

{ "platform" : "all" }

          { "platform" : "all" }

此代碼塊在浮窗中顯示

指定特定推播平台：

{ "platform": [ "android", "ios" ] }

          {
  "platform": [
    "android",
    "ios"
  ]
}

此代碼塊在浮窗中顯示

notification

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

關鍵字	類型	選項	含義	說明
alert	String 或 JSON Object	必填	內容	訊息內容本身。若 android、ios 下冇有指定 alert，則以此為準。
android	JSON Object	選填	android 平台屬性	android 平台推播參數，詳情參考 android 說明
ios	JSON Object	選填	ios 平台屬性	ios 平台推播參數，詳情參考 ios 說明

alert

這個位置的 "alert" 屬性（直接在 notification 對象下），是一個快捷定義，各平台的 alert 信息如果都一樣，則可不定義平台下的 alert，以此為準。如果各平台有定義，則覆蓋這裏的定義。

{ "notification" : { "alert" : "Hello, Push!" } }

          {
  "notification" : {
    "alert" : "Hello, Push!"
  }
}

此代碼塊在浮窗中顯示

上面定義的 notification 對象，將被推播到 "platform" 指定的多個平台，並且其通知 alert 信息都一樣。

android

Android 平台上的通知，被 MTPush SDK 按照一定的通知欄樣式展示。支持的字段如下：

關鍵字	類型	選項	含義	說明
alert	String 或 JSON Object	必填	通知內容	這裏指定後會覆蓋上級統一指定的 alert 信息。內容可以為空字符串，表示不展示到通知欄。各推播通道對此字段的限製詳見推播限製。
title	String	可選	通知標題	如果指定了，則通知裏原來展示 App 名稱的地方，將展示 title。各推播通道對此字段的限製詳見推播限製。
builder_id	Int	可選	通知欄樣式ID	Android SDK 可設定通知欄樣式，這雷根據樣式 ID 來指定該使用哪套樣式。
channel_id	String	可選	Android 通知欄通道 ID	不超過 1000 字節，Android 8.0 開始可以進行NotificationChannel 配置，這雷根據 channel ID 來指定通知欄展示效果。
priority	Int	可選	通知欄展示優先級	預設為 0，範圍為 -2～2。
category	String	可選	通知欄條目過濾或排序	完全依賴 rom 廠商對 category 的處理策略。
style	Int	可選	通知欄樣式類型	用來指定通知欄樣式類型，預設為 0。 1：bigText 2：Inbox 3：bigPicture
big_text	String	可選	大文本通知欄樣式	當 style = 1 時可用，內容會被通知欄以大文本的形式展示出來。支持 api 16 以上的 rom。
inbox	JSONObject	可選	文本條目通知欄樣式	當 style = 2 時可用， json 的每個 key 對應的 value 會被當作文本條目逐條展示。支持 api 16 以上的 rom。
big_pic_path	String	可選	文本條目通知欄樣式	當 style = 3 時可用，目前支持 .jpg 和 .png 格式的圖片。支持網路圖片 url、在地圖片的 path，如果是 http／https 的 url，會自動下載；如果要指定開發者準備的在地圖片就填 sdcard 的相對路徑。支持 api 16 以上的 rom。
extras	JSON Object	可選	擴展字段	這裏自訂 JSON 格式的 Key/Value 信息，以供業務使用。
intent	JSON Object	可選	指定跳轉頁面(推薦)	使用 intent 裡的 url 指定點擊通知欄後跳轉的目標頁面。建議填寫 intent 字段，否則點擊通知可能無跳轉動作。此字段支持以下三種類型: 跳轉到目標頁: intent:#Intent;action=action 路徑;component= 包名 /Activity 全名;end 應用首頁: intent:#Intent;action=android.intent.action.MAIN;end (固定為此地址) 跳轉到deeplink地址: scheme://test?key1=val1&key2=val2
large_icon	String	可選	通知大圖示	圖示大小不超過 300 k。支持網路圖片 url、在地圖片的 path，如果是 http／https 的 url，會自動下載；如果要指定開發者準備的在地圖片就填 sdcard 的相對路徑。
small_icon	String	可選	通知小圖示	通知小圖示，圖示路徑可以是以 http 或 https 開頭的網路圖片，大小不能超過 300 k。若冇有填充廠商 small_icon_uri，則預設使用該 small_icon 字段展示。
sound	String	可選	鈴聲	填寫 Android 專案中 /res/raw/ 路徑下鈴聲文件名稱，無需文件名字尾。註意：針對 Android 8.0 以上，當傳遞了 channel_id 時，此屬性不生效。
badge_add_num	Int	可選	設定角標數字纍加值，在原角標的基礎上進行纍加	此屬性目前僅針對華為 EMUI 8.0 及以上、小米 MIUI 6 及以上、vivo 設備走廠商通道時生效。此字段如果不填，表示不改變角標數字（小米設備由於係統控製，不論推播走 Engagelab 通道下發還是廠商通道下發，即使不傳遞依舊是預設 +1 的效果）。取值範圍為：1-99，若設定了取值範圍內的數字，下一條通知欄訊息配置的 badge_add_num 數據會和原角標數量進行相加，建議取值為 1。舉例：badge_add_num 取值為 1，原角標數為 2，傳送此角標訊息後，應用程式角標數顯示為 3。
badge_class	String	可選	桌面圖示對應的應用程式入口 Activity 類，比如“com.test.badge.MainActivity”	僅華為通道推播時生效，此值如果填寫非主 Activity 類，以廠商限製邏輯為準。若需要實現角標纍加功能，需配合 badge_add_num 使用，二者需要共存，缺少其一不可。

{ "notification": { "android": { "alert": "hello, MTPush!", "title": "Push test", "builder_id": 3, "style": 1, "big_text": "big text content", "inbox":JSONObject, "big_pic_path": "picture url", "priority": 0, "category": "category str", "large_icon": "http://push.api.engagelab.cc/largeIcon.jpg", "small_icon": "http://www.small.com/small_icon.jpg", "intent": { "url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end" }, "extras": { "news_id": 134, "my_key": "a value" } } } }

          {
    "notification": {
        "android": {
            "alert": "hello, MTPush!",
            "title": "Push test",
            "builder_id": 3,
            "style": 1,
            "big_text": "big text content",
            "inbox":JSONObject,
            "big_pic_path": "picture url",
            "priority": 0,
            "category": "category str",
            "large_icon": "http://push.api.engagelab.cc/largeIcon.jpg",
            "small_icon": "http://www.small.com/small_icon.jpg",
            "intent": {
                "url": "intent:#Intent;component=push.api.engagelab.cc/com.example.mtpushdemo.SettingActivity;end"
            },
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代碼塊在浮窗中顯示

ios

iOS 平台上 APNs 通知。

該通知內容會由 MTPush 代理發往 Apple APNs 服務器，並在 iOS 設備上在係統通知的方式呈現。

該通知內容滿足 APNs 的規範，支持的字段如下：

關鍵字	類型	選項	含義	說明
alert	String 或 JSON Object	必填	通知內容	這裏指定內容將會覆蓋上級統一指定的 alert 信息。內容為空則不展示到通知欄。支持字符串形式也支持官方定義的 alert payload。結構，在該結構中包含 title 和 subtitle 等官方支持的 key。
sound	String 或 JSON Object	可選	通知提示聲音	普通通知： String 類型。如果無此字段，則此訊息無聲音提示；有此字段，如果找到了指定的聲音就播放該聲音，否則播放預設聲音。如果此字段為空字符串，iOS 7 為預設聲音，iOS 8 及以上係統為無聲音。告警通知： JSON Object , 支持官方定義的 payload 結構，在該結構中包含 critical 、name 和 volume 等官方支持的 key 。
badge	Int 或 String	可選	應用程式角標	可設定為 N、+N、-N，N 的取值範圍為 [0,99]。若上載的角標值 value 為 10，表示角標會設定為 N、10+N、10-N（值小於 0 時預設清除角標）。為 0 或空字符串，則表示清除角標。如果不填，表示不改變角標數字。 MTPush 官方 API Library(SDK) 會預設填充badge值為"+1"。
content-available	Boolean	可選	推播喚醒	推播的時候攜帶"content-available":true 說明是 Background Remote Notification，如果不攜帶此字段則是普通的Remote Notification。詳情參考：Background Remote Notification
mutable-content	Boolean	可選	通知擴展	iOS 10 新增的 Notification Service Extension 功能，用於上報每條 APNs 信息的送達狀態，使用該功能需要客戶端實現 Service Extension 接口，並在服務端使用 mutable-content 字段完成設定。 true：說明支持 iOS 10 的UNNotificationServiceExtension 功能。如果不攜帶此字段則是普通的 Remote Notification，無法統計抵達數據。
category	String	可選	iOS 分类	iOS 8 才支持。設定APNs payload中的"category"字段值。
extras	JSON Object	可選	擴展字段	這裏自訂 Key/value 信息，以供業務使用。
thread-id	String	可選	通知分組	iOS 的遠程通知通過該屬性來對通知進行分組，同一個 thread-id 的通知歸為一組。
interruption-level	String	可選	通知優先級和交付時間的中斷級別	iOS 15 的通知級別，取值隻能是 active,critical,passive,timeSensitive 中的一個，詳情參考：UNNotificationInterruptionLevel。

iOS 通知 MTPush 要轉發給 APNs 服務器。 MTPush 中 Notification + Message 長度限製為 4000 個字節。 MTPush 在推播時使用 utf-8 編碼，所以一個漢字佔用 3 個字節長度。

服務端傳送示例：

{ "notification": { "ios": { "alert": "hello, Push!", "sound": "sound.caf", "badge": 1, "extras": { "news_id": 134, "my_key": "a value" } } } }

          {
    "notification": {
        "ios": {
            "alert": "hello, Push!",
            "sound": "sound.caf",
            "badge": 1,
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

此代碼塊在浮窗中顯示

客戶端收到的訊息：

{ "_j_msgid" = 813843507; aps = { alert = "hello,Push!"; badge = 1; sound = "sound.caf"; }; "my_key" = "a value"; "news_id" = 134; }

          {
  "_j_msgid" = 813843507;
  aps =     {
  alert = "hello,Push!";
  badge = 1;
  sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}

此代碼塊在浮窗中顯示

message

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

此部分內容不會展示到通知欄上，MTPush SDK 收到訊息內容後透傳給 App。App 需要自行處理。
iOS 在推播應用程式內訊息通道（非 APNS）獲取此部分內容，需 App 處於前台。

支持的字段如下：

關鍵字	類型	選項	含義
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 Android 端用戶已經收到，如果通知欄還未清除，則新的訊息內容會覆蓋之前這條通知。覆蓋功能起作用的時限是：1 天，如果在覆蓋指定時限內該 msg_id 不存在，則返回 7006 錯誤，提示不是一次有效的訊息覆蓋操作，當前的訊息不會被推播。該字段僅對 Android 有效僅支持Engagelab 通道、小米通道、魅族通道、OPPO 通道、FCM 通道、華為通道（EMUI10 及以上的設備）。
apns_production	Boolean	可選	APNs 是否生産環境	該字段僅對 iOS 的 Notification 有效，如果不指定則為推播生産環境。註意：MTPush 官方 API LIbrary (SDK) 預設設定為推播 “開發環境”。 true：表示推播生産環境。 false：表示推播開發環境。
apns_collapse_id	String	可選	更新 iOS 通知的標識符	APNs 新通知如果匹配到當前通知中心有相同 apns-collapse-id 字段的通知，則會用新通知內容來更新它，並使其置於通知中心首位。 collapse id 長度不可超過 64 bytes。
big_push_duration	Int	可選	定速推播時長(分鍾)	又名緩慢推播，把原本盡可能快的推播速度，降低下來，給定的 n 分鍾內，均勻地嚮這次推播的目標用戶推播；最大值為 1440。最多能同時存在 20 條定速推播。未設定則不是定速推播。
multi_language	json object	可選	多語言推送設置	推送內容多語言適配設置，詳情查看 multi_language 說明。
third_party_channel	JSON Object	可選	Android 廠商通道配置信息	僅針對配置了廠商通道的用戶有效參數詳情查看 third_party_channel 說明。

multi_language

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

請求參數

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

請求示例

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

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

此代碼塊在浮窗中顯示

返回示例

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

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

此代碼塊在浮窗中顯示

third_party_channel

本字段用來填寫 Android 廠商通道的個性化信息，key 隻支持 xiaomi、huawei、meizu、oppo、vivo、fcm 這6 個 Android 廠商通道，可以為其中一個或者多個同時存在，每個廠商類型的 KEY 當前可包含如下幾個可選項：

關鍵字	類型	選項	含義	說明
distribution_new	String	必選	Engagelab 和廠商通道並存時，設定下發優先級	取值不能為空字符串。 mtpush：表示推送强制走 Engagelab 通道下发。 pns_mtpush：表示表示针对 fcm+ 国内厂商组合类型用户，推送强制优先走小米 / 华为 / 魅族 /oppo/vivo/荣耀通道下发，无效再走engagelab通道。 mtpush_pns：表示针对 fcm+ 国内厂商组合类型用户，推送优先走engagelab，engagelab不在线再走厂商通道，厂商作为辅助。 fcm_mtpush：表示表示针对 fcm+ 国内厂商组合类型用户，推送强制优先走 fcm 通道下发，无效再走engagelab通道 mtpush_fcm：表示针对 fcm+ 国内厂商组合类型用户，推送优先走engagelab，engagelab不在线再走 fcm 通道，fcm 作为辅助。注：针对pns_mtpush/fcm_mtpush/mtpush_pns/mtpush_fcm这四种策略而言，如果设备可用的系统推送通道仅有一种（FCM或者手机厂商），则会忽略强制优先级，走集成成功的系统通道。
channel_id	String	可選	通知欄訊息分類	支持 OPPO 的私信、小米的通知訊息、華為訊息分類類別，分類 ChannelID 值需開發者自行嚮廠商申請。
classification	Int	可選	通知欄訊息分類	vivo 手機廠商通知欄訊息分類，不填預設為 0。 0：代錶營運訊息。 1：代錶係統訊息。目前 vivo 對係統訊息分類較為嚴格，具體規則參考：vivo。
pushMode	Int	可選	vivo推播模式	不填預設為 0。詳情參考 vivo pushMode，使用測試推播需要手動在 vivo 後台配置測試設備的 ID 。 0：表示正式推播。 1：表示測試推播。
importance	String	可選	華為通知欄訊息智能分類	為了適配華為手機廠商的通知欄訊息智能分類，對應華為的 importance 字段，不填充預設為 "NORMAL"，參考：華為通知訊息智能分類。 LOW：一般訊息。 NORMAL：重要訊息。 HIGH：非常重要訊息。
urgency	String	可選	華為廠商自訂訊息優先級	為了適配華為手機廠商自訂訊息的優先級。 HIGH：非常重要訊息，HIGH 級別訊息到達用戶手機時可強製拉起應用程式進程。 NORMAL：重要訊息。設定“HIGH”需要嚮華為申請特殊權限，參考：特殊權限如何申請。
category	String	可選	華為廠商自訂訊息場景標識	為了適配華為手機廠商自訂訊息，標識高優先級透傳訊息的特殊場景，或用於標識訊息類型以對特定類型訊息加快傳送，對應值及其說明參考：category 值說明。
small_icon_uri	String	可選	廠商訊息小圖示樣式	目前支持小米 / 華為廠商。優先使用廠商字段，廠商字段冇有填充，則使用 android 內的 small_icon 字段。小米支持小米廠商的大圖示 id，華為、支持 Engagelab 的 media_id 及廠商在地路徑。(小米官方後續不再支持自訂小圖示，建議開發者不要繼續使用小米 small Icon 相關特性功能)。
small_icon_color	String	可選	小米廠商小圖示樣式顔色	為了適配小米廠商的訊息小圖示樣式顔色，不填充預設是灰色 (小米官方後續不在支持自訂小圖示，建議開發者不要繼續使用小米 small icon 相關特性功能)。
only_use_vendor_style	Boolean	可選	是否使用自身通道設定樣式	是否隻使用自身通道設定的樣式，不使用 android 裏面設定的樣式，預設為 false， true：隻使用自身通道設定的樣式。 false：可使用 android 裏面設定的樣式。

調用示例如下：

"third_party_channel": { "xiaomi": { "distribution_new": "mtpush", "channel_id": "*******", "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png", "small_icon_color": "#ABCDEF", }, "huawei": { "distribution_new": "mtpush_pns", "importance": "NORMAL", "small_icon_uri": "https://xx.com/xx.jpg", "only_use_vendor_style": true }, "meizu": { "distribution_new": "mtpush" }, "fcm": { "distribution_new": "mtpush" }, "oppo": { "distribution_new": "mtpush", "channel_id": "*******", "large_icon": "3653918_5f92b5739ae676f5745bcbf4", }, "vivo": { "distribution_new": "mtpush", "classification": 0, "pushMode": 0 } }

          "third_party_channel": {
    "xiaomi": {
        "distribution_new": "mtpush",
        "channel_id": "*******",
        "small_icon_uri": "http://f6.market.xiaomi.com/download/MiPass/x/x.png",
        "small_icon_color": "#ABCDEF",
    },
    "huawei": {
        "distribution_new": "mtpush_pns",
        "importance": "NORMAL",
        "small_icon_uri": "https://xx.com/xx.jpg",
        "only_use_vendor_style": true
    },
    "meizu": {
        "distribution_new": "mtpush"
    },
    "fcm": {
        "distribution_new": "mtpush"
    },
    "oppo": {
        "distribution_new": "mtpush",
        "channel_id": "*******",
        "large_icon": "3653918_5f92b5739ae676f5745bcbf4",
    },
    "vivo": {
        "distribution_new": "mtpush",
        "classification": 0,
        "pushMode": 0
    }
}

此代碼塊在浮窗中顯示

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 長度限製為 2048 字節	400
21008	app_key 參數非法	必須改正，請仔細對比你所傳的 appkey 是否與應用程式程式資訊中的一緻，是否多了空格	400
21009	係統內部錯誤	必須改正	400
21011	冇有滿足條件的推播目標	請檢查 to 字段	400
21015	請求參數校驗失敗	存在非預期的參數	400
21016	請求參數校驗失敗	參數類型錯誤，或者參數長度超出限製	400
21030	內部服務超時	稍後重試	503
23006	參數錯誤	定速推播 big_push_duration 超過最大值 1440	400
27000	係統記憶體錯誤	請重試	500
27001	參數錯誤	校驗信息為空	401
27008	參數錯誤	third_party_channel 裏面的 distribution 不為空，但是 notification 的 alert 內容為空	401
27009	參數錯誤	third_party_channel 中 distribution 格式無效或為空	401

推播限製

廠商通道	標題長度	內容長度	敏感詞	其他說明
Engagelab 通道	不限製，但限製訊息體總大小	不限製，但限製訊息體總大小	-	MTPush 中 Notification + Message 長度限製為 4000 個字節。
華為通道	＜ 40 個字符	＜ 1024 字符	禁止攜帶政府，領導人名稱、台獨等相關內容	預設【營銷通知】的權限為靜默通知，靜默推播冇有聲音、震動等提示。
魅族通道	＜ 32 個字符	＜ 100 個字符	禁止特殊字符，如：#	中英文字符均計算為 1 個字符。部分訊息可能會存入魅族手機右上角【魅族訊息盒子】中。
小米通道	＜ 50 個字符	＜ 128 個字符	禁止特殊字符，如：#、>>	中英文字符均計算為 1 個字符。部分訊息可能會存在通知欄的不重要通知裏。
OPPO 通道	＜ 32 個字符	＜ 200 個字符	暫無說明	中英文字符均計算為 1 個字符。預設關閉通知權限。
vivo 通道	＜ 40 個字符	＜ 100 個字符	禁止特殊字符，如：#、>> 正式訊息禁止：純數字、純英文、純符號、符號加數字，測試、test、大括號、中括號等	英文為 1 個字符，中文為 2 個字符。預設關閉通知權限。同設備 1 天內營運訊息的推播條數不能超過 5 條。同設備 1 天內不能重複推播內容相同的營運訊息。
APNS 通道	＜ 20 個字符（40 個英文字符）	通知中心和鎖屏狀態最多顯示 110 個字符，55 個漢字。頂部彈窗最多顯示 62 個字符，31 個漢字，超過部分會顯示省略號。	暫無說明	暫無

多语言码

語言	Language	Language Code
英語	English	en
阿拉伯語	Arabic	ar
簡體中文	Chinese (Simplified)	zh-Hans
繁體中文	Chinese (Traditional)	zh-Hant
捷克語	Czech	cs
丹麥語	Danish	da
荷蘭語	Dutch	nl
法語	French	fr
德語	German	de
印地語	Hindi	hi
意大利語	Italian	it
日語	Japanese	ja
韓語	Korean	ko
馬來語	Malay	ms
俄語	Russian	ru
西班牙語	Spanish	es
泰語	Turkish	th
越南語	Vietnamese	vi