範本管理 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

请求参数

参数	类型	选项	说明
name	String	選填	範本名稱，注意該字段使用的是模糊匹配
language_code	String	選填	範本語言，參見語言代碼
category	String	選填	範本類別。 ● AUTHENTICATION：驗證碼 ● MARKETING：市場營銷 ● UTILITY：服務通知
status	String	選填	範本狀態： APPROVED - 審核通過 PENDING - 審核中 REJECTED - 審核拒絕 PENDING_DELETION - 刪除中 DELETED - 已刪除 DISABLED - 停用（被封禁） IN_APPEAL - 申訴中 PAUSED - 暫停使用開發者需要關注的主要是 APPROVED/PENDING/REJECTED/DISABLED

返回參數

參數	類型	選項	說明
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 - 審核通過 PENDING - 審核中 REJECTED - 審核拒絕 PENDING_DELETION - 刪除中 DELETED - 已刪除 DISABLED - 停用（被封禁） IN_APPEAL - 申訴中 PAUSED - 暫停使用開發者需要關注的主要是 APPROVED/PENDING/REJECTED/DISABLED

返回示例

// 一個 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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示模板變量
            }
        ]
    },
    ......
]

此代碼塊在浮窗中顯示

查詢範本資訊

調用地址

GET https://wa.api.engagelab.cc/v1//{template_id}

其中 {template_id} 為需要查詢範本ID。

請求參數

無

請求示例

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

返回參數

參數	類型	選項	說明
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

返回示例

{ "id": "406979728071589", // 範本id "name": "code", // 範本名稱 "language": "zh_TW", // 範本語言 "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": "406979728071589", // 範本id
    "name": "code", // 範本名稱
    "language": "zh_TW", // 範本語言
    "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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示範本變數
        }
    ]
}

此代碼塊在浮窗中顯示

創建範本

調用地址

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

語言代碼

語言	Code
南非荷蘭文	af
阿爾巴尼亞文	sq
阿拉伯文	ar
亞塞拜然文	az
孟加拉文	bn
保加利亞文	bg
加泰隆尼亞文	ca
中文（中國大陸）	zh_CN
中文（中國香港）	zh_HK
中文（中國台灣）	zh_TW
克羅埃西亞文	hr
捷克文	cs
丹麥文	da
荷蘭文	nl
英文	en
英文（英國）	en_GB
英文（美國）	en_US
愛沙尼亞文	et
菲律賓文	fil
芬蘭文	fi
法文	fr
格魯吉亞文	ka
德文	de
希臘文	el
古吉拉特文	gu
豪沙文	ha
希伯來文	he
印度文	hi
匈牙利文	hu
印尼文	id
愛爾蘭文	ga
義大利文	it
日文	ja
康納達文	kn
哈薩克文	kk
盧安達文	rw_RW
韓文	ko
吉爾吉斯斯坦文	ky_KG
寮文	lo
拉脫維亞文	lv
立陶宛文	lt
馬其頓文	mk
馬來文	ms
馬拉雅拉姆文	ml
馬拉提文	mr
挪威文	nb
波斯文	fa
波蘭文	pl
葡萄牙文（巴西）	pt_BR
葡萄牙文（葡萄牙）	pt_PT
旁遮普文	pa
羅馬尼亞文	ro
俄羅斯文	ru
塞爾維亞文	sr
斯洛伐克文	sk
斯洛維尼亞文	sl
西班牙文	es
西班牙文（阿根廷）	es_AR
西班牙文（西班牙）	es_ES
西班牙文（墨西哥）	es_MX
斯瓦西里文	sw
瑞典文	sv
坦米爾文	ta
特拉古文	te
泰文	th
土耳其文	tr
烏克蘭文	uk
晤魯都文	ur
烏茲別克文	uz
越南文	vi
祖魯文	zu

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

範本管理 API

概述

調用驗證

獲取範本列表

調用地址

请求参数

返回參數

返回示例

查詢範本資訊

調用地址

請求參數

請求示例

返回參數

返回示例

創建範本

調用地址

調用示例

請求參數

components 對象

header 頁眉組件

example 對象說明

body 正文組件

example 對象說明

footer 頁腳組件

buttons 按鈕組件

buttons 對象說明

返回參數

成功返回

失敗返回

更新範本

調用地址

調用示例

請求參數

返回參數

成功返回

失敗返回

刪除範本

調用地址

返回參數

成功返回

失敗返回

錯誤碼

註釋

媒體訊息格式要求

語言代碼