範本管理 API

概述

使用範本管理 API 可以對 WABA 的範本進行增刪改查操作，並透過自訂標籤對範本分組。本文件包含兩類介面：

範本介面：獲取範本列表、查詢範本資訊、上傳範例媒體檔案、創建範本、更新範本、刪除範本。
標籤介面：獲取範本標籤列表、創建範本標籤、修改範本標籤、刪除範本標籤、設定範本標籤。標籤在目前 API 金鑰所屬的 WABA 內生效，僅用於 EngageLab 側的範本管理，不修改 WhatsApp 範本內容，不觸發 Meta 重新審核。

調用驗證

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
tag_id	String	選填	標籤 ID，用於依標籤篩選範本。取值規則：不傳或傳空字串 - 不依標籤篩選傳標籤 ID - 只回傳設定了該標籤的範本傳 `ungrouped` - 只回傳未設定任何標籤的範本，不區分大小寫

tag_id 與 name、language_code、category、status 等查詢條件為 AND 關係，目前不支援一次傳入多個標籤。tag_id 格式不合法時回傳錯誤碼 3002，標籤不存在或不屬於目前 WABA 時回傳錯誤碼 4001。

注意：若 WABA 內存在名稱為「未分組」或 ungrouped 的標籤，依該標籤篩選時須傳入其數字標籤 ID；直接傳 ungrouped 一律按「篩選未設定標籤的範本」處理。

請求示例

依標籤篩選：

GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

此代碼塊在浮窗中顯示

篩選未設定標籤的範本：

GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

此代碼塊在浮窗中顯示

返回參數

參數	類型	選項	說明
id	String	必填	範本 ID
name	String	必填	範本名稱
language	String	必填	範本語言，參見語言代碼。
category	String	必填	範本類別。 AUTHENTICATION MARKETING UTILITY
components	Object Array	必填	範本內容的組件，參考創建範本中的 components 對象
status	String	必填	範本狀態： APPROVED - 審核通過 PENDING - 審核中 REJECTED - 審核拒絕 PENDING_DELETION - 刪除中 DELETED - 已刪除 DISABLED - 停用（遭封鎖） IN_APPEAL - 申訴中 PAUSED - 暫停使用開發者需要關注的主要是 APPROVED/PENDING/REJECTED/DISABLED
tags	Object Array	必填	目前範本設定的標籤，未設定標籤時回傳空陣列。 tags[].id - String，標籤 ID tags[].name - String，標籤名稱

返回示例

// 一個 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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示範本變數 } ], "tags": [ // 該範本設定的標籤，未設定標籤時為空陣列 { "id": "101", "name": "物流通知" } ] }, ...... ]

              
              // 一個 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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示範本變數
            }
        ],
        "tags": [ // 該範本設定的標籤，未設定標籤時為空陣列
            {
                "id": "101",
                "name": "物流通知"
            }
        ]
    },
    ......
]

此代碼塊在浮窗中顯示

查詢範本資訊

調用地址

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

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

請求參數

NULL

請求示例

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

              
              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
tags	Object Array	必填	目前範本設定的標籤，未設定標籤時回傳空陣列。 tags[].id - String，標籤 ID tags[].name - String，標籤名稱

返回示例

{ "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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示範本變數 } ], "tags": [ // 該範本設定的標籤，未設定標籤時為空陣列 { "id": "101", "name": "物流通知" } ] }

              
              {
    "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 分鐘內輸入。" // 兩個大括號{{}}括起來的表示範本變數
        }
    ],
    "tags": [ // 該範本設定的標籤，未設定標籤時為空陣列
        {
            "id": "101",
            "name": "物流通知"
        }
    ]
}

此代碼塊在浮窗中顯示

上傳範例媒體檔案

在創建或編輯包含多媒體（image、video、document）頁眉的範本時，Meta 要求先將媒體檔案上傳到 Meta 官方伺服器。本 API 提供將範本範例檔案上傳並獲取 handle_id 的功能，該 ID 需填入創建/編輯範本介面的 header_handle 欄位中。

調用地址

POST https://wa.api.engagelab.cc/v1/media/handles

請求參數

Content-Type: multipart/form-data

參數	類型	選項	說明
file	file	必填	範例媒體檔案。大小限制 20 MB，格式要求參見媒體訊息格式要求。

請求示例

POST '/v1/media/handles' --header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' --form 'file=@"/Users/demo/files/demopic.jpeg"'

              
              POST '/v1/media/handles' 
--header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' 
--form 'file=@"/Users/demo/files/demopic.jpeg"'

此代碼塊在浮窗中顯示

返回參數

成功返回

欄位	類型	選項	描述
handle_id	String	必選	Meta 回傳的檔案識別碼，用於創建/編輯範本時填入 `example.header_handle` 欄位。

返回示例：

{ "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY" }

              
              {
    "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY"
}

此代碼塊在浮窗中顯示

失敗返回

HTTP 狀態碼為 4xx 或者 5xx，回應體包含欄位如下：

欄位	類型	選項	描述
code	int	必選	錯誤碼
message	String	必選	錯誤詳情

返回示例：

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

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

此代碼塊在浮窗中顯示

創建範本

調用地址

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，必須傳入透過上傳範例媒體檔案 API 獲取的 handle_id。
header_text	String Array	可選	當 format 為 text 且包含變數時，對此欄位傳入該變數的替換值。例如："header_text": ["var1"]

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`"]

驗證碼類型的特別說明

注意事項

針對身分驗證類別（即 AUTHENTICATION）的範本：

在 Components 中請不要設定 HEADER 組件。
範本內容文字會根據範本的語言 language 欄位自動進行在地化設定。
針對 ONE_TAP 跳轉 App 的模式，目前僅支援 Android 應用程式，且 必須在你的 App 中進行相關握手處理，詳細使用教學請閱讀官方文件-身分驗證範本。
創建範本時提交的參數欄位，與創建成功後 WhatsApp 側記錄的範本欄位是不一致的，本質上 WhatsApp 側會將該類別範本中的 BODY、FOOTER 以及 BUTTONS 做替換，所以下發範本訊息時請特別注意，需要新增 button 變數，具體參考訊息傳送 API 文件。

COPY_CODE 示例

提交的資料：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body 是必須的 "type": "BODY", "add_security_recommendation": true // 是否新增安全建議描述 }, { // footer 是可選的 "type": "FOOTER", "code_expiration_minutes": 2 // 新增過期時間顯示，範圍[1,90]，不新增則不傳該欄位 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "copy_code", "text": "copy it" // 長度限制 25 字元 } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body 是必須的
            "type": "BODY",
            "add_security_recommendation": true  // 是否新增安全建議描述
            
        },
        {
            // footer 是可選的
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // 新增過期時間顯示，範圍[1,90]，不新增則不傳該欄位
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "copy_code",
                    "text": "copy it"      // 長度限制 25 字元
                }
            ]
        }
    ]
}

此代碼塊在浮窗中顯示

創建成功後，WhatsApp 側實際得到的範本內容：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* 是你的驗證碼。為安全起見，請不要分享這組驗證碼。", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "這組驗證碼將在 2 分鐘後過期。" }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "Copy code", "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}", "example": [ "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456" ] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* 是你的驗證碼。為安全起見，請不要分享這組驗證碼。",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "這組驗證碼將在 2 分鐘後過期。"
        },
        {
            "type": "BUTTONS",
            "buttons": [{
              "type": "URL",
              "text": "Copy code",
              "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}",
              "example": [
                  "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456"
              ]
          }]
        }
    ]
}

此代碼塊在浮窗中顯示

ONE_TAP 示例

提交的資料：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body是必須的 "type": "BODY", "add_security_recommendation": true // 是否新增安全建議描述 }, { // footer是可選的 "type": "FOOTER", "code_expiration_minutes": 2 // 新增過期時間顯示，範圍[1,90]，不新增則不傳該欄位 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "one_tap", "text": "auto1", // 長度限制25字元 "autofill_text": "auto1", // 長度限制25字元 "package_name": "ppssd", "signature_hash": "asds" } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body是必須的
            "type": "BODY",
            "add_security_recommendation": true  // 是否新增安全建議描述
            
        },
        {
            // footer是可選的
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // 新增過期時間顯示，範圍[1,90]，不新增則不傳該欄位
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "one_tap",
                    "text": "auto1",      // 長度限制25字元
                    "autofill_text": "auto1",      // 長度限制25字元
                    "package_name": "ppssd",    
                    "signature_hash": "asds"  
                }
            ]
        }
    ]
}

此代碼塊在浮窗中顯示

創建成功後，WhatsApp 側實際得到的範本內容：

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* 是你的驗證碼。為安全起見，請不要分享這組驗證碼。", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "這組驗證碼將在 2 分鐘後過期。" }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "copy1", "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp{{1}}", "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp123456"] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* 是你的驗證碼。為安全起見，請不要分享這組驗證碼。",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "這組驗證碼將在 2 分鐘後過期。"
        },
        {
            "type": "BUTTONS",
            "buttons": [{
                "type": "URL",
                "text": "copy1",
                "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp{{1}}",
                "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp123456"]
            }]
        }
    ]
}

此代碼塊在浮窗中顯示

返回參數

成功返回

參數	類型	選項	說明
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", // 內容區塊 "text": "define var as {{1}}", "example": { "body_text": [["var1"]] } },{ "type": "HEADER", "format": "image", // 內容類型：image/video/document "example": { // 注意：此處必須填入上傳介面回傳的 handle_id，不再支援直接填寫圖片 URL "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."] } },{ "type": "FOOTER", "text": "footer only support text without variable" },{ "type": "BUTTONS", "buttons": [{ "type": "PHONE_NUMBER", "text": "this is a phone number", "phone_number": "8613800138000" }] }] }

              
              {
    "components": [{                        // 範本內容
        "type": "BODY",                     // 內容區塊
        "text": "define var as {{1}}", 
        "example": {
            "body_text": [["var1"]]
        }
    },{
        "type": "HEADER",
        "format": "image",                  // 內容類型：image/video/document
        "example": {
            // 注意：此處必須填入上傳介面回傳的 handle_id，不再支援直接填寫圖片 URL
            "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."]
        }
    },{
        "type": "FOOTER",
        "text": "footer only support text without variable"
    },{
        "type": "BUTTONS",
        "buttons": [{                                     
            "type": "PHONE_NUMBER",              
            "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"
}

此代碼塊在浮窗中顯示

獲取範本標籤列表

回傳目前 API 金鑰所屬 WABA 下的全部標籤，不分頁。

調用地址

GET https://wa.api.engagelab.cc/v1/template-tags

請求參數

NULL

請求示例

GET https://wa.api.engagelab.cc/v1/template-tags

              
              GET https://wa.api.engagelab.cc/v1/template-tags

此代碼塊在浮窗中顯示

返回參數

參數	類型	選項	說明
id	String	必填	標籤 ID
name	String	必填	標籤名稱
template_count	Integer	必填	目前 WABA 內設定了該標籤的範本數量。同名多語言範本按範本 ID 分別計數

返回示例

[ { "id": "101", "name": "物流通知", "template_count": 3 }, { "id": "102", "name": "售後客服", "template_count": 0 } ]

              
              [
    {
        "id": "101",
        "name": "物流通知",
        "template_count": 3
    },
    {
        "id": "102",
        "name": "售後客服",
        "template_count": 0
    }
]

此代碼塊在浮窗中顯示

WABA 下無標籤時回傳空陣列 []。

創建範本標籤

調用地址

POST https://wa.api.engagelab.cc/v1/template-tags

請求參數

參數	類型	選項	說明
name	String	必填	標籤名稱，長度 1～64 個字元，命名要求參見標籤名稱規則。

請求示例

{ "name": "物流通知" }

              
              {
    "name": "物流通知"
}

此代碼塊在浮窗中顯示

返回參數

成功返回

參數	類型	選項	說明
id	String	必填	標籤 ID
name	String	必填	規範化後的標籤名稱

{ "id": "101", "name": "物流通知" }

              
              {
    "id": "101",
    "name": "物流通知"
}

此代碼塊在浮窗中顯示

失敗返回

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

{ "code": 3003, "message": "template tag name already exists" }

              
              {
    "code": 3003,
    "message": "template tag name already exists"
}

此代碼塊在浮窗中顯示

修改範本標籤

調用地址

PUT https://wa.api.engagelab.cc/v1/template-tags/{tag_id}

其中 {tag_id} 為需要修改的標籤 ID。

請求參數

參數	類型	選項	說明
name	String	必填	新的標籤名稱，長度 1～64 個字元，命名要求參見標籤名稱規則。

請求示例

{ "name": "售後客服" }

              
              {
    "name": "售後客服"
}

此代碼塊在浮窗中顯示

返回參數

成功返回

參數	類型	選項	說明
id	String	必填	標籤 ID
name	String	必填	修改後的標籤名稱

{ "id": "101", "name": "售後客服" }

              
              {
    "id": "101",
    "name": "售後客服"
}

此代碼塊在浮窗中顯示

失敗返回

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

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代碼塊在浮窗中顯示

刪除範本標籤

調用地址

DELETE https://wa.api.engagelab.cc/v1/template-tags/{tag_id}
注意：刪除標籤僅解除範本與該標籤的關聯，不刪除範本，不影響範本傳送

其中 {tag_id} 為需要刪除的標籤 ID。

請求參數

NULL

請求示例

DELETE https://wa.api.engagelab.cc/v1/template-tags/101

              
              DELETE https://wa.api.engagelab.cc/v1/template-tags/101

此代碼塊在浮窗中顯示

返回參數

成功返回

參數	類型	選項	說明
affected_template_count	Integer	必填	本次解除關聯的範本數量。同名多語言範本按範本 ID 分別計數

{ "affected_template_count": 3 }

              
              {
    "affected_template_count": 3
}

此代碼塊在浮窗中顯示

失敗返回

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

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代碼塊在浮窗中顯示

設定範本標籤

調用地址

PUT https://wa.api.engagelab.cc/v1/templates/{template_id}/tags
注意：本介面為全量覆蓋，tag_ids 傳入的是範本儲存後的完整標籤集合，未包含在內的原有標籤將被解除關聯

其中 {template_id} 為需要設定標籤的範本 ID。

請求參數

參數	類型	選項	說明
tag_ids	String Array	必填	範本儲存後的完整標籤 ID 集合，須明確傳入且不能為 `null`。所有 ID 須屬於目前 WABA，重複 ID 自動去重。

tag_ids 取值說明：

傳入 [] 表示清空該範本的全部標籤。
未傳 tag_ids 或傳入 null 時請求失敗，不會清空原有標籤。
請求失敗時範本的標籤集合保持不變，可直接重試。
不限制單個範本的標籤數量，可傳入目前 WABA 的全部標籤。

請求示例

{ "tag_ids": ["101", "102"] }

              
              {
    "tag_ids": ["101", "102"]
}

此代碼塊在浮窗中顯示

返回參數

成功返回

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

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

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

此代碼塊在浮窗中顯示

失敗返回

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

範本不存在或不屬於目前 WABA：

{ "code": 4001, "message": "template not found" }

              
              {
    "code": 4001,
    "message": "template not found"
}

此代碼塊在浮窗中顯示

標籤不存在或不屬於目前 WABA：

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

此代碼塊在浮窗中顯示

未傳 tag_ids 或傳入 null：

{ "code": 3002, "message": "template tag IDs must be provided as an array" }

              
              {
    "code": 3002,
    "message": "template tag IDs must be provided as an array"
}

此代碼塊在浮窗中顯示

錯誤碼

下表中的「標籤介面」即概述中列出的五個標籤介面，另包含獲取範本列表中傳入 tag_id 篩選的場景。

錯誤碼	http code	適用介面	說明
1000	500	全部介面	內部錯誤
2001	401	全部介面	EngageLab 側鑑權失敗，未攜帶有效資料格式的 token
2002	401	全部介面	EngageLab 側鑑權失敗，token 已過期或已被停用
2003	400	全部介面	WhatsApp 側鑑權失敗，請聯絡 EngageLab 客服處理
2004	403	全部介面	無調用此 API 的權限，或相關帳號、WABA 已被停用
3001	400	全部介面	請求參數格式無效，請檢查是否採用 JSON 格式，以及欄位類型是否符合要求
3002	400	全部介面	請求參數有誤，請檢查請求參數是否符合要求
3002	400	標籤介面	標籤名稱為空
3002	400	標籤介面	標籤名稱超過 64 個字元，參見標籤名稱規則
3002	400	標籤介面	標籤名稱包含不允許的字元，參見標籤名稱規則
3002	400	標籤介面	標籤 ID 格式無效，須為正整數字串
3002	400	標籤介面	設定範本標籤時未傳 tag_ids，或其值為 null
3003	400	全部介面	請求參數有誤，相關業務校驗失敗
3003	400	標籤介面	同一 WABA 內已存在相同的標籤名稱，判重時不區分大小寫和重音符號
3003	400	標籤介面	單個 WABA 的標籤數量已達到 20 個上限
3003	400	標籤介面	標籤操作繁忙，稍後重試即可，重試不會產生重複資料
4001	400	全部介面	範本不存在或不屬於目前 WABA
4001	400	標籤介面	標籤不存在或不屬於目前 WABA
5002	400	全部介面	範本請求在 Meta 處理失敗，詳情參考 message 欄位的錯誤描述

註釋

媒體訊息格式要求

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

標籤名稱規則

創建和修改標籤時，伺服端先對名稱做規範化處理，再校驗長度和重複。

規範化：去除首尾空白，並將名稱中連續的空白字元合併為一個空格。例如提交 " 物流通知 "，實際儲存和回傳的名稱為 "物流通知"。

字元限制：允許空格、底線、短橫線、各語言的可見字元和 emoji；不允許換行符、定位字元、控制字元和不可見格式字元。

長度：規範化後須為 1～64 個字元。長度按 Unicode 碼位計算，一個 emoji 可能佔用多個碼位。

判重：同一 WABA 內名稱不可重複，判重時不區分大小寫和重音符號，例如 Logistics、logistics、Logístics 視為同一名稱。無保留字限制。

標籤使用限制

單個 WABA 最多創建 20 個標籤。
不限制單個範本的標籤數量，可設定目前 WABA 已有的全部標籤，因此實際上限為 20 個。
標籤 ID 在請求和回傳中均為字串（如 "101"），請勿按數字類型解析。
同名多語言範本按各自的範本 ID 獨立設定標籤，例如同一範本的中英文版本需要分別設定。
標籤不寫入 Meta，不修改範本狀態和品質評分，不觸發重新審核。

語言代碼

語言	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

概述

調用驗證

獲取範本列表

調用地址

請求參數

請求示例

返回參數

返回示例

查詢範本資訊

調用地址

請求參數

請求示例

返回參數

返回示例

上傳範例媒體檔案

調用地址

請求參數

請求示例

返回參數

成功返回

失敗返回

創建範本

調用地址

調用示例

請求參數

components 對象

header 頁眉組件

example 對象說明

body 正文組件

example 對象說明

footer 頁腳組件

buttons 按鈕組件

buttons 對象說明

驗證碼類型的特別說明

注意事項

COPY_CODE 示例

ONE_TAP 示例

返回參數

成功返回

失敗返回

更新範本

調用地址

調用示例

請求參數

返回參數

成功返回

失敗返回

刪除範本

調用地址

返回參數

成功返回

失敗返回

獲取範本標籤列表

調用地址

請求參數

請求示例

返回參數

返回示例

創建範本標籤

調用地址

請求參數

請求示例

返回參數

成功返回

失敗返回

修改範本標籤

調用地址

請求參數

請求示例

返回參數

成功返回

失敗返回

刪除範本標籤

調用地址

請求參數

請求示例

返回參數

成功返回

失敗返回