範本管理 API

概述

使用範本管理 API 可以對 WABA 的範本進行增刪改查操作。

調用驗證

EngageLab REST API 採用 HTTP 基本認證的驗證方式：HTTP Header（頭）裏加 Authorization：

Authorization: Basic ${base64_auth_string}

          Authorization: Basic ${base64_auth_string}

此代碼塊在浮窗中顯示

上述 base64_auth_string 的生成算法為：base64(dev_key:dev_secret)

Header 名稱是 "Authorization"，值是 base64 轉換過的 "username:password" 對（中間有個冒號）。
在 WhatsApp API 的場景裏，username 是 DevKey，password 是 DevSecret。請在控製台-配置管理- API 金鑰頁面獲取。

獲取範本

調用地址

GET https://wa.api.engagelab.cc/v1/templates

返回示例

// 一個 json 數組，數組中每一個對象都是範本信息 [ { "id": "406979728071589", // 範本id "name": "code", // 範本名稱 "language": "zh_CN", // 範本語言 "status": "APPROVED", // 狀態，APPROVED為審核通過可用 "category": "OTP", // 類別，目前支援 OTP/TRANSACTIONAL/MARKETING "components": [ // 範本具體內容，可包含 HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // 類型，支援 text/image/location/video/document，預設TEXT "text": "註冊驗證碼" // 文本內容，當format為text時，為必選項 }, { "type": "BODY", "text": "您的驗證碼是 {{1}}，請於 5 分鍾內輸入。" // 兩個大括號{{}}括起來的表示範本變數 } ] }, ...... ]

          // 一個 json 數組，數組中每一個對象都是範本信息
[
    {
        "id": "406979728071589", // 範本id
        "name": "code", // 範本名稱
        "language": "zh_CN", // 範本語言
        "status": "APPROVED", // 狀態，APPROVED為審核通過可用
        "category": "OTP", // 類別，目前支援 OTP/TRANSACTIONAL/MARKETING
        "components": [ // 範本具體內容，可包含 HEADER/BODY/FOOTER/BUTTON
            {
                "type": "HEADER",
                "format": "text", // 類型，支援 text/image/location/video/document，預設TEXT
                "text": "註冊驗證碼" // 文本內容，當format為text時，為必選項
            },
            {
                "type": "BODY",
                "text": "您的驗證碼是 {{1}}，請於 5 分鍾內輸入。" // 兩個大括號{{}}括起來的表示範本變數
            }
        ]
    },
    ......
]

此代碼塊在浮窗中顯示

返回參數

參數	類型	選項	說明
id	String	必填	範本 ID
name	String	必填	範本名字
language	String	必填	範本語言，參見語言代碼。
category	String	必填	範本類別。 OTP：免洗密碼 MARKETING：市場營銷 TRANSACTIONAL：交易事務註意：範本類別最晚在 2023 年 5 月 1 日更新為： AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	範本內容的組件，參考創建範本中的 components 對象
status	String	必填	範本狀態： APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED

創建範本

調用地址

POST https://wa.api.engagelab.cc/v1/templates

調用示例

{ "name": "template_name", // 範本名稱，允許同名範本，僅支援小寫字母及數字及下劃線 "language": "zh_CN", // 範本語言，同名範本下不允許同語言範本 "category": "OTP", // 類別，目前支援 OTP/TRANSACTIONAL/MARKETING "components": [ { // 範本內容 "type": "BODY", // 內容塊，目前支援 HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}" // 具體文本，當body為text時不需要傳format字段 "example": { "body_text": [ [ "var1" ] ] } }, { "type": "HEADER", "format": "image", // 內容類型，支援 text/image/video/document/location "example": { "header_handle": [ "https://jiguang.cn/demopic.jpg" ] } }, { "type": "FOOTER", "text": "footer only support text without variable" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", // 按鈕類型，支援 PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" } ] } ] }

          {
    "name": "template_name", // 範本名稱，允許同名範本，僅支援小寫字母及數字及下劃線
    "language": "zh_CN", // 範本語言，同名範本下不允許同語言範本
    "category": "OTP", // 類別，目前支援 OTP/TRANSACTIONAL/MARKETING
    "components": [
        { // 範本內容
            "type": "BODY", // 內容塊，目前支援 HEADER/BODY/FOOTER/BUTTONS
            "text": "define var as {{1}}" // 具體文本，當body為text時不需要傳format字段
          "example": {
                "body_text": [
                    [
                        "var1"
                    ]
                ]
            }
        },
        {
            "type": "HEADER",
            "format": "image", // 內容類型，支援 text/image/video/document/location
            "example": {
                "header_handle": [
                    "https://jiguang.cn/demopic.jpg"
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "footer only support text without variable"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER", // 按鈕類型，支援 PHONE_NUMBER/URL/QUICK_REPLY              
                    "text": "this is a phone number",
                    "phone_number": "8613800138000"
                }
            ]
        }
    ]
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	選項	說明
name	String	必填	模版名字，僅支援小寫字母、數字及下劃線，不超過 512 個字符。
language	String	必填	模版語言，參見語言代碼。
category	String	必填	模版類別。 OTP：免洗密碼 MARKETING：市場營銷 TRANSACTIONAL：交易事務註意：範本類別最晚在 2023 年 5 月 1 日更新為： AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	描述範本內容的組件，參考 components 對象說明；註意必須包含 type=BODY 的 components。

components 對象

本對象用於描述範本內容。範本分為「頁眉 HEADER」「正文 BODY」「頁腳 FOOTER」「按鈕 BUTTONS」幾個組件，使用 type 來指定，不同的組件類型支援的參數不同，如下：

header 組件整體是可選的，如果不需要設定頁眉，請不要設定此組件

參數	類型	選項	說明
type	String	必填	組件類型，取值 HEADER
format	String	必填	頁眉格式，取值：text、image、video、document，對應著文本、圖片、視訊、文件。
text	String	可選	頁眉文本內容，當 format=text 時需設定此字段內容。頁眉文本內容中可以設定變數，但僅支援設定 1 個變數，用 {{1}} 進行表示。
example	JSON Object	可選	頁眉示例，當 text 包含變數或 format 為媒體類型時，此字段必填。參考 example 對象說明

example 對象說明

參數	類型	選項	說明
header_handle	String Array	可選	當 format 為 image、video、document 時，對此字段傳入對應類型的媒體的 url，且 url 能被訪問，否則模版審核可能被拒絕。例如："header_handle": ["`https://jiguang.cn/demopic.jpg`"]
header_text	String Array	可選	當 format 為 text 且包含變數時，對此字段傳入該變數的替換值。例如："header_text": ["var1"]
header_url	String Array	可選	與header_handle的用法一緻，註意此字段在 WhatsApp 未來的版本中將不再支援，盡量避免使用。例如："header_url": ["`https://jiguang.cn/demopic.jpg`"]

body 正文組件

body 組件是必填的，必須設定正文內容。

參數	類型	選項	說明
type	String	必填	組件類型，取值 BODY
text	String	必填	正文內容，最長不超過 1024 個字符，支援設定多個變數，變數由兩個大括號加變數序號組成，序號序號需要從 1 開始，保持遞增，如 {{1}} 和 {{2}} 。
example	JSON Object	可選	正文示例，Meta 審核人員將根據示例判斷你的訊息合規性。參考 example 對象說明，當 text 包含變數時，此字段必填。

example 對象說明

參數	類型	選項	說明
body_text	String Array	可選	當 text 包含變數時，需要對此字段傳入所有變數的替換值，按變數序號的順序依次填寫。例如："body_text": [["var1","var2","var3"]]

footer 組件整體是可選的，如果不需要設定頁腳，請不要設定此組件

參數	類型	選項	說明
type	String	必填	組件類型，取值 FOOTER
text	String	必填	頁腳內容，隻能設定純文本內容，不能定義變數。

buttons 按鈕組件

buttons 組件整體是可選的，如果不需要設定按鈕，請不要設定此組件

參數	類型	選項	說明
type	String	必填	組件類型，取值 BUTTONS
buttons	Object Array	必填	按鈕信息，參考 buttons 對象說明。

buttons 對象說明

參數	類型	選項	說明
type	String	必填	按鈕類型，取值： QUICK_REPLY、URL、PHONE_NUMBER，對應：快速回複、瀏覽網站、撥打電話號碼
text	String	必填	按鈕上的文字說明，不能包含變數，為純文本，最長 25 個字符
url	String	可選	當 type=URL 時必填，可以在網址的結尾設定變數，且僅支援設定 1 個變數，用 {{1}} 進行表示。
phone_number	String	可選	當 type=PHONE_NUMBER 時必填，不能包含變數，內容為包含國際區號的電話號碼。
example	String Array	可選	當 type=QUICK_REPLY 和 type=URL 時必填例如："example": ["`https://www.website.com/dynamic-url-example`"]

返回參數

成功返回

參數	類型	選項	說明
template_id	String	必填	範本 ID，成功時返回

{ "template_id": "1275172986566180" // 範本id }

          {
    "template_id": "1275172986566180"		// 範本id
}

此代碼塊在浮窗中顯示

失敗返回

參數	類型	選項	說明
code	int	必填	錯誤碼，失敗時返回
message	String	必填	錯誤信息，失敗時返回

{ "code": 5002, "message": "Invalid parameter. code:100:2388042" }

          {
    "code": 5002,
    "message": "Invalid parameter. code:100:2388042"
}

此代碼塊在浮窗中顯示

更新範本

調用地址

PUT https://wa.api.engagelab.cc/v1/templates/{templateId}

調用示例

{ "components": [{ // 範本內容 "type": "BODY", // 內容塊，目前支援 HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}" // 具體文本，當body為text時不需要傳format字段 "example": { "body_text": [["var1"]] } },{ "type": "HEADER", "format": "image", // 內容類型，支援 text/image/video/document/location "example": { "header_url": ["https://jiguang.cn/demopic.jpg"] } },{ "type": "FOOTER", "text": "footer only support text without variable" },{ "type": "BUTTONS", "buttons": [{ "type": "PHONE_NUMBER", // 按鈕類型，支援 PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" }] }] }

          {
   "components": [{						// 範本內容
        "type": "BODY",					// 內容塊，目前支援 HEADER/BODY/FOOTER/BUTTONS
        "text": "define var as {{1}}" // 具體文本，當body為text時不需要傳format字段
          "example": {
              "body_text": [["var1"]]
        }
    },{
        "type": "HEADER",
        "format": "image",				// 內容類型，支援 text/image/video/document/location
          "example": {
              "header_url": ["https://jiguang.cn/demopic.jpg"]
          }
    },{
                "type": "FOOTER",
                "text": "footer only support text without variable"
        },{
          "type": "BUTTONS",
          "buttons": [{                                    
            "type": "PHONE_NUMBER",         	// 按鈕類型，支援 PHONE_NUMBER/URL/QUICK_REPLY              
            "text": "this is a phone number",             
            "phone_number": "8613800138000"
            }]
      }]
}

此代碼塊在浮窗中顯示

請求參數

同創建模版接口的請求參數。

返回參數

成功返回

參數	類型	選項	說明
code	int	必填	返回碼，固定為 0
message	String	必填	返回信息，固定為success

{ "code": 0, "message": "success" }

          {
    "code": 0,
    "message": "success"
}

此代碼塊在浮窗中顯示

失敗返回

參數	類型	選項	說明
code	int	必填	錯誤碼，失敗時返回
message	String	必填	錯誤信息，失敗時返回

{ "code": 5002, "message": "Invalid parameter. code:100:2593002" }

          {
    "code": 5002,
    "message": "Invalid parameter. code:100:2593002"
}

此代碼塊在浮窗中顯示

刪除範本

調用地址

DELETE https://wa.api.engagelab.cc/v1/templates/{template_name}
註意：此處傳遞的是範本名稱並非範本 ID，將刪除該範本名稱的所有語言的範本內容

返回參數

成功返回

參數	類型	選項	說明
code	int	必填	返回碼，固定為 0
message	String	必填	返回信息，固定為success

{ "code": 0, "message": "success" }

          {
    "code": 0,
    "message": "success"
}

此代碼塊在浮窗中顯示

失敗返回

參數	類型	選項	說明
code	int	必填	錯誤碼，失敗時返回
message	String	必填	錯誤信息，失敗時返回

{ "code": 2004, "message": "something error" }

          {
    "code": 2004,
    "message": "something error"
}

此代碼塊在浮窗中顯示

錯誤碼

錯誤碼	http code	說明
1000	500	內部錯誤
2001	401	EngageLab 側鑒權失敗，未攜帶有效數據格式的 token
2002	401	EngageLab 側鑒權失敗，token已過期或已被禁用
2003	400	WhatsApp 側鑒權失敗，請聯係 EngageLab 客服處理
2004	403	無調用此 API 的權限
3001	400	請求參數格式無效，請檢查是否採用 JSON 格式
3002	400	請求參數有誤，請檢查請求參數是否符合要求
3003	400	請求參數有誤，相關業務校驗失敗
4001	400	範本不存在
5002	400	範本請求在 Meta 處理失敗，詳情參考 message 字段的錯誤描述

註釋

媒體訊息格式要求

媒體類型	支援的格式類型 Content-Type	大小限製
image	image/jpeg, image/png，不支援透明背景	5 MB
video	video/mp4	16MB
document	僅支援 PDF 格式	100 MB

語言代碼

相關語言和對應代碼的對應關係，請下載本文件查看：
範本語言代碼.xlsx

範本管理 API

概述

調用驗證

獲取範本

調用地址

返回示例

返回參數

創建範本

調用地址

調用示例

請求參數

components 對象

header 頁眉組件

example 對象說明

body 正文組件

example 對象說明

footer 頁腳組件

buttons 按鈕組件

buttons 對象說明

返回參數

成功返回

失敗返回

更新範本

調用地址

調用示例

請求參數

返回參數

成功返回

失敗返回

刪除範本

調用地址

返回參數

成功返回

失敗返回

錯誤碼

註釋

媒體訊息格式要求

語言代碼