訊息傳送 API

使用訊息傳送 API 可以將 WhatsApp 的訊息傳送能力集成到你的業務係統中。
在調用 API 之前，請先在控製台 API 金鑰頁面創建密鑰。

調用地址

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

調用驗證

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 金鑰頁面獲取。

請求示例

請求頭

POST /v1/messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

          POST /v1/messages  
HTTP/1.1  Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

此代碼塊在浮窗中顯示

請求體

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "code", "language": "zh_CN", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "12345" } ] } ] } }, "request_id": "123asdbbqwe9faweg", "custom_args": { "arg1": "string val", "arg2": 123 } }

           {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {
            "name": "code",
            "language": "zh_CN",
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "12345"
                        }
                    ]
                }
            ]
        }
    },
    "request_id": "123asdbbqwe9faweg",
    "custom_args": {
        "arg1": "string val",
        "arg2": 123
    }
}

此代碼塊在浮窗中顯示

請求參數

一個請求對象以 JSON 格式錶達，因此請求頭需要帶 Content-Type: application/json 。

參數	類型	選項	說明
from	String	選填	傳送號
to	String Array	必填	傳送目標的電話號碼
body	JSON Object	必填	訊息體
request_id	String	選填	自訂的請求 ID，用來標識是哪條請求，回響時返回。
custom_args	JSON Object	選填	自訂的信息，在訊息狀態回調中返回給開發者。

from

參數	類型	選項	說明
from	String	選填	傳送號，即用於傳送訊息的企業電話號碼。需要加上國際區號，未填寫時使用預設傳送號（需要在控製台配置）

to

參數	類型	選項	說明
to	String Array	必填	傳送目標的 WhatsApp 電話號碼，需要加上國際區號

body

一個訊息體，包含的字段如下：

參數	類型	選項	說明
type	string	必填	訊息類型，目前支援： template：範本訊息 text：文本訊息 image：圖片訊息 audio：音頻訊息 video：視訊訊息 document：文檔訊息 sticker：貼紙訊息僅 template 訊息才能主動傳送給用戶，其餘類型的訊息要求用戶在 24 小時內回複過訊息，才能被送達。其中圖片/音頻/視訊/文檔/貼紙皆為媒體訊息，註意遵循媒體訊息格式要求。
template	template object	可選	當 type=template 時使用，詳見 template object 說明。
text	text object	可選	當 type=text 時使用，詳見 text object 說明
image	image object	可選	當 type=image 時使用，詳見 image object 說明。
audio	audio object	可選	當 type=audio 時使用，詳見 audio object 說明。
video	video object	可選	當 type=video 時使用，詳見 video object 說明。
document	document object	可選	當 type=document 時使用，詳見 document object 說明。
sticker	sticker object	可選	當 type=sticker 時使用，詳見 sticker object 說明。

text object 說明

文本訊息

參數	類型	選項	說明
body	String	必填	文本內容，WhatsApp 要求不超過 4096 個字符/character

示例

{ "from": "8613800138000", //傳送方的電話號碼 "to": "8613800138000", //收件人的電話號碼 "body": { "type": "text", //訊息類型 "text": { "body": "your-text-message-content" //訊息內容 } } }

          {
    "from": "8613800138000", //傳送方的電話號碼
    "to": "8613800138000", //收件人的電話號碼
    "body": {
        "type": "text", //訊息類型
        "text": {
            "body": "your-text-message-content" //訊息內容
        }
    }
}

此代碼塊在浮窗中顯示

image object 說明

圖片訊息

參數	類型	選項	說明
id	String	可選	WhatsApp 生成的 media_id ；id 和 link 其一必須有值。
link	String	可選	圖片鏈接，http/https 鏈接，註意遵循媒體訊息格式要求。
caption	String	可選	對圖片的描述，不超過 1024 個字符。

示例

{ "from": "8613800138000",//傳送方的電話號碼 "to": "8613800138000",//收件人的電話號碼 "body": { "type": "image",//訊息類型 "image": { "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //圖片鏈接 "caption": "caption info" // 可選，圖片下方的文本描述，1024個字符內 } } }

          {
  "from": "8613800138000",//傳送方的電話號碼
  "to": "8613800138000",//收件人的電話號碼
    "body": {			
            "type": "image",//訊息類型
            "image": {
                "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //圖片鏈接
        "caption": "caption info"   // 可選，圖片下方的文本描述，1024個字符內
            }
    }
}

此代碼塊在浮窗中顯示

video object 說明

視訊訊息

參數	類型	選項	說明
id	String	可選	WhatsApp 生成的 media_id ；id 和 link 其一必須有值。
link	String	可選	視訊鏈接，http/https 鏈接，註意遵循媒體訊息格式要求。
caption	String	可選	對視訊的描述，不超過 1024 個字符。

示例

{ "from": "8613800138000",//傳送方的電話號碼 "to": "8613800138001", //收件人的電話號碼 "body": { "type": "video",//訊息類型 "video": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //視訊鏈接 "caption": "caption info" // 可選，視訊下方的文本描述，1024個字符內 } } }

          {
  "from": "8613800138000",//傳送方的電話號碼
  "to": "8613800138001",  //收件人的電話號碼
    "body": {			
            "type": "video",//訊息類型
            "video": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //視訊鏈接
        "caption": "caption info"   // 可選，視訊下方的文本描述，1024個字符內
            }
    }
}

此代碼塊在浮窗中顯示

audio object 說明

音頻訊息

參數	類型	選項	說明
id	String	可選	WhatsApp 生成的 media_id ；id 和 link 其一必須有值。
link	String	可選	音頻鏈接，http/https 鏈接，註意遵循媒體訊息格式要求。

示例

{ "from": "8613800138000",//傳送方的電話號碼 "to": "8613800138001", //收件人的電話號碼 "body": { "type": "audio",//訊息類型 "audio": { "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音頻鏈接 } } }

          {
  "from": "8613800138000",//傳送方的電話號碼
  "to": "8613800138001",  //收件人的電話號碼
    "body": {
            "type": "audio",//訊息類型
            "audio": {
                "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音頻鏈接
            }
    }
}

此代碼塊在浮窗中顯示

document object 說明

文件訊息

參數	類型	選項	說明
id	String	可選	WhatsApp 生成的 media_id ；id 和 link 其一必須有值。
link	String	可選	文檔鏈接，http/https 鏈接，註意遵循媒體訊息格式要求。
caption	String	可選	對文件的描述，不超過 1024 個字符。
filename	String	可選	文件名稱。若未填寫`filename`字段而填寫了`caption`字段，則會以`caption`作為文件名；若填寫了`filename`則會以`filename`的值作為文件名。

示例

{ "from": "8613800138000",//傳送方的電話號碼 "to": "8613800138001", //收件人的電話號碼 "body": { "type": "document",//訊息類型 "document": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //文件鏈接 "caption": "caption info", // 可選，文件下方的文本描述，1024個字符內 "filename": "document file name" // 可選，文件名稱 } } }

          {
  "from": "8613800138000",//傳送方的電話號碼
  "to": "8613800138001",  //收件人的電話號碼
    "body": {
            "type": "document",//訊息類型
            "document": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //文件鏈接
        "caption": "caption info",   // 可選，文件下方的文本描述，1024個字符內
        "filename": "document file name"    // 可選，文件名稱
            }
    }
}

此代碼塊在浮窗中顯示

sticker object 說明

貼紙訊息

參數	類型	選項	說明
id	String	可選	whatsapp 側的 media_id ；id 和 link 其一必須有值。
link	String	可選	貼紙鏈接，http/https 鏈接，註意遵循媒體訊息格式要求。

示例

{ "from": "8613800138000",//傳送方的電話號碼 "to": "8613800138001", //收件人的電話號碼 "body": { "type": "sticker",//訊息類型 "sticker": { "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //貼紙鏈接 } } }

          {
  "from": "8613800138000",//傳送方的電話號碼
  "to": "8613800138001",  //收件人的電話號碼
    "body": {
            "type": "sticker",//訊息類型
            "sticker": {
                "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //貼紙鏈接
            }
    }
}

此代碼塊在浮窗中顯示

template object 說明

範本訊息，需要先創建範本，可以在控製台操作或調用 API 創建。

參數	類型	類型	說明
name	String	必填	範本名稱。可以在控製台-訊息範本頁面找到，僅支援小寫數字及下劃線。
language	String	必填	範本語言代碼。創建範本時對同一個範本名稱可以設定多個語言的內容，因此傳送時需要使用 name 和 language 字段共同決定所選範本。
components	components-object array	可選	當範本中存在可變變數時，需要填充此字段，數組中僅設定 1 個 components 對象元素即可。

template.components object 說明

參數	類型	選項	說明
type	String	必填	範本組件，範本中哪一個組件包含變數，就需要對該組件傳值，取值： header：頁眉 body：正文 footer：頁腳 button：按鈕
parameters	parameters object	必填	設定可變變數內容

template.components.parameters object 說明

參數	類型	選項	說明
type	string	必填	變數內容的類型，取值 text、currency、date_time、image、video、document。多媒體素材類型（image、video、document）僅在頁眉（header）中存在，素材支援的格式請參考媒體訊息格式要求。
text	string	可選	當 type=text 時使用，為可變變數的具體內容
date_time	localizable object	可選	當 type=date_time 時使用，與 text 區別在於可在地化適配顯示。
currency	localizable object	可選	當 type=currency 時使用，與 text 區別在於可在地化適配顯示。
image	image object	可選	當 type=image 時使用，與 image object 內容格式一緻。
video	video object	可選	當 type=video 時使用，與 video object 內容格式一緻。
document	document object	可選	當 type=document 時使用，與 document object 內容格式一緻。

示例

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "your-template-name", "language": "zh_CN", "components": [ { "type" : "header", "parameters": [{ "type": "document", "document": { "link": "http(s)://the-url", "filename": "your-document-filename" } }] }, { "type": "body", "parameters": [ { "type": "text", "text": "your-text-string" }, { "type": "currency", "currency": { "fallback_value": "$100.99", "code": "USD", "amount_1000": 100990 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "day_of_week": 5, "day_of_month": 25, "year": 1977, "month": 2, "hour": 15, "minute": 33 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "timestamp": 1485470276 } } ] } ] } } }

          {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {          
            "name": "your-template-name",
                        "language": "zh_CN",
            "components": [
              {
                "type" : "header",
                "parameters": [{
                         "type": "document",
                         "document": {
                             "link": "http(s)://the-url",
                             "filename": "your-document-filename"
                       }
                }]
              },
              {
                 "type": "body",
                 "parameters": [
                        {
                            "type": "text",
                            "text": "your-text-string"
                        },
                        {
                            "type": "currency",
                            "currency": {
                                "fallback_value": "$100.99",
                                "code": "USD",
                                "amount_1000": 100990
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "day_of_week": 5,
                                "day_of_month": 25,
                                "year": 1977,
                                "month": 2,
                                "hour": 15,
                                "minute": 33
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "timestamp": 1485470276
                            }
                        }
                    ]
                }
            ]
        }
    }
}

此代碼塊在浮窗中顯示

返回參數

成功返回

字段	類型	選項	描述
message_id	String	必選	EngageLab WhatsApp 的訊息 ID，唯一標識某一條訊息。
request_id	String	可選	請求時提交的自訂 ID，回響時原樣返回。

{ "message_id": "cbggf4if6o9ukqaalfug", "request_id": "your-sendno-string" }

          {
    "message_id": "cbggf4if6o9ukqaalfug",
    "request_id": "your-sendno-string"
}

此代碼塊在浮窗中顯示

失敗返回

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"
}

此代碼塊在浮窗中顯示

錯誤碼

錯誤碼	http code	說明
1000	500	內部錯誤
2001	401	EngageLab 側鑒權失敗，未攜帶有效數據格式的 token。
2002	401	EngageLab 側鑒權失敗，token已過期或已被禁用。
2003	400	WhatsApp 側鑒權失敗，請聯係 EngageLab 客服處理。
2004	403	無調用此 API 的權限，請檢查您是否有對該 API 秘鑰授權了訊息傳送 API （某傳送號）的權限。
3001	400	請求參數格式無效，請檢查是否採用 JSON 格式。
3002	400	請求參數有誤，請檢查請求參數是否符合要求。
3003	400	請求參數有誤，相關業務校驗失敗，詳情參考 message 字段的錯誤描述。
4001	400	相關資源不存在，如模版訊息下發時使用了不存在的模版。

註釋

媒體訊息格式要求

媒體類型	支援的格式類型 Content-Type	大小限製
image	image/jpeg, image/png，不支援透明背景	5 MB
video	video/mp4, video/3gpp 註：編碼上僅支援 H.264 視訊編碼和 AAC 音頻編碼	16MB
audio	audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus（註：基礎的 audio/ogg 不支援，僅支援 audio/ogg; codecs=opus）	16MB
document	1、傳送文件訊息時，支援任何的 MIME-type 類型 2、傳送範本訊息時，頁眉中的文件僅支援 PDF 格式	100 MB
sticker	image/webp	Static stickers:100KB Animated stickers: 500KB 512x512 像素

語言代碼

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