ส่งข้อความ API
ด้วยการใช้ API การส่งข้อความ คุณสามารถผสานความสามารถในการส่งข้อความของ WhatsApp เข้ากับระบบธุรกิจของคุณได้
ก่อนเรียกใช้ API โปรดสร้างคีย์ในหน้าคอนโซล API Keys
Endpoint
POST https://wa.api.engagelab.cc/v1/messages
การยืนยันตัวตน
EngageLab REST API ใช้ HTTP Basic Authentication: เพิ่ม Authorization ใน HTTP Header:
Authorization: Basic ${base64_auth_string}
อัลกอริธึมการสร้าง base64_auth_string ด้านบนคือ: base64(dev_key:dev_secret)
- ชื่อ Header คือ "Authorization" และค่าคือคู่ "username:password" ที่ถูกเข้ารหัส base64 (มีเครื่องหมายโคลอนคั่นกลาง)
- ในกรณีของ WhatsApp API ชื่อผู้ใช้คือ DevKey และรหัสผ่านคือ DevSecret โปรดรับข้อมูลเหล่านี้ในหน้าคอนโซล - การจัดการการกำหนดค่า - API Keys
ตัวอย่างคำขอ
Header ของคำขอ
POST /v1/messages
HTTP/1.1 Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Body ของคำขอ
{
"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 ดังนั้น Header ของคำขอต้องรวม Content-Type: application/json
พารามิเตอร์ | ประเภท | จำเป็นหรือไม่ | คำอธิบาย |
---|---|---|---|
from | String | ไม่จำเป็น | หมายเลขผู้ส่ง |
to | String Array | จำเป็น | หมายเลขโทรศัพท์ของผู้รับ |
body | JSON Object | จำเป็น | เนื้อหาข้อความ |
request_id | String | ไม่จำเป็น | รหัสคำขอที่กำหนดเองเพื่อระบุคำขอ จะถูกส่งกลับในคำตอบ |
custom_args | JSON Object | ไม่จำเป็น | ข้อมูลที่กำหนดเองที่ส่งกลับไปยังนักพัฒนาในสถานะข้อความ callback |
from
พารามิเตอร์ | ประเภท | จำเป็นหรือไม่ | คำอธิบาย |
---|---|---|---|
from | String | ไม่จำเป็น | หมายเลขผู้ส่ง เช่น หมายเลขโทรศัพท์ธุรกิจที่ใช้ส่งข้อความ ต้องรวมรหัสประเทศ หากไม่ได้ระบุ จะใช้หมายเลขผู้ส่งเริ่มต้น (ต้องกำหนดค่าใน console) |
to
พารามิเตอร์ | ประเภท | จำเป็นหรือไม่ | คำอธิบาย |
---|---|---|---|
to | String Array | จำเป็น | หมายเลขโทรศัพท์ WhatsApp ของผู้รับ ต้องรวมรหัสประเทศ |
body
เนื้อหาข้อความที่มีฟิลด์ดังต่อไปนี้:
พารามิเตอร์ | ประเภท | จำเป็นหรือไม่ | คำอธิบาย |
---|---|---|---|
type | string | จำเป็น | ประเภทข้อความที่รองรับในปัจจุบัน: เฉพาะข้อความแม่แบบที่สามารถส่งถึงผู้ใช้ได้โดยตรง ประเภทข้อความอื่น ๆ ต้องการให้ผู้ใช้ตอบกลับภายใน 24 ชั่วโมงเพื่อให้สามารถส่งได้ Image/Audio/Video/Document/Sticker เป็นข้อความสื่อทั้งหมด โปรดปฏิบัติตาม ข้อกำหนดรูปแบบข้อความสื่อ |
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 ตัวอักษร |
ตัวอย่าง
{
"from": "8613800138000", //หมายเลขโทรศัพท์ผู้ส่ง
"to": ["8613800138000"], //หมายเลขโทรศัพท์ผู้รับ
"body": {
"type": "text", //ประเภทข้อความ
"text": {
"body": "your-text-message-content" //เนื้อหาข้อความ
}
}
}
คำอธิบาย image object
ข้อความรูปภาพ
พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
id | String | ไม่จำเป็น | media_id ที่สร้างโดย WhatsApp; 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 ตัวอักษร
}
}
}
คำอธิบาย video object
ข้อความวิดีโอ
พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
id | String | ไม่จำเป็น | media_id ที่สร้างโดย WhatsApp; id หรือ link ต้องมีค่า |
link | String | ไม่จำเป็น | ลิงก์วิดีโอ ลิงก์ http/https โปรดปฏิบัติตาม ข้อกำหนดรูปแบบข้อความสื่อ |
caption | String | ไม่จำเป็น | คำอธิบายของวิดีโอ สูงสุด 1024 ตัวอักษร |
ตัวอย่าง
{
"from": "8613800138000",//หมายเลขโทรศัพท์ผู้ส่ง
"to": ["8613800138000"], //หมายเลขโทรศัพท์ผู้รับ
"body": {
"type": "video",//ประเภทข้อความ
"video": {
"link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //ลิงก์วิดีโอ
"caption": "caption info" // ไม่จำเป็น คำอธิบายข้อความใต้ลิงก์วิดีโอ สูงสุด 1024 ตัวอักษร
}
}
}
คำอธิบาย audio object
ข้อความเสียง
พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
id | String | ไม่จำเป็น | media_id ที่สร้างโดย WhatsApp; id หรือ link ต้องมีค่า |
link | String | ไม่จำเป็น | ลิงก์เสียง ลิงก์ http/https โปรดปฏิบัติตาม ข้อกำหนดรูปแบบข้อความสื่อ |
ตัวอย่าง
{
"from": "8613800138000",//หมายเลขโทรศัพท์ผู้ส่ง
"to": ["8613800138000"], //หมายเลขโทรศัพท์ผู้รับ
"body": {
"type": "audio",//ประเภทข้อความ
"audio": {
"link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //ลิงก์เสียง
}
}
}
คำอธิบาย document object
ข้อความเอกสาร
พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
id | String | ไม่จำเป็น | media_id ที่สร้างโดย WhatsApp; id หรือ link ต้องมีค่า |
link | String | ไม่จำเป็น | ลิงก์เอกสาร ลิงก์ http/https โปรดปฏิบัติตาม ข้อกำหนดรูปแบบข้อความสื่อ |
caption | String | ไม่จำเป็น | คำอธิบายของเอกสาร สูงสุด 1024 ตัวอักษร |
filename | String | ไม่จำเป็น | ชื่อไฟล์ หากไม่ได้ระบุฟิลด์ filename แต่ฟิลด์ caption มีค่า ฟิลด์ caption จะถูกใช้เป็นชื่อไฟล์; หากระบุ filename ค่าของมันจะถูกใช้เป็นชื่อไฟล์ |
ตัวอย่าง
{
"from": "8613800138000",//หมายเลขโทรศัพท์ผู้ส่ง
"to": ["8613800138000"], //หมายเลขโทรศัพท์ผู้รับ
"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 | ไม่จำเป็น | media_id ที่สร้างโดย WhatsApp; id หรือ link ต้องมีค่า |
link | String | ไม่จำเป็น | ลิงก์สติกเกอร์ ลิงก์ http/https โปรดปฏิบัติตาม ข้อกำหนดรูปแบบข้อความสื่อ |
ตัวอย่าง
{
"from": "8613800138000",//หมายเลขโทรศัพท์ผู้ส่ง
"to": ["8613800138000"], //หมายเลขโทรศัพท์ผู้รับ
"body": {
"type": "sticker",//ประเภทข้อความ
"sticker": {
"link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //ลิงก์สติกเกอร์
}
}
}
คำอธิบายวัตถุเทมเพลต
ข้อความเทมเพลตต้องสร้างเทมเพลตก่อน ซึ่งสามารถทำได้ผ่าน การดำเนินการในคอนโซล หรือ การสร้างผ่าน API
พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
name | String | จำเป็น | ชื่อเทมเพลต สามารถพบได้ในหน้า Console - Message Templates และรองรับเฉพาะตัวอักษรตัวพิมพ์เล็ก ตัวเลข และขีดล่างเท่านั้น |
language | String | จำเป็น | รหัสภาษา ของเทมเพลต เมื่อสร้างเทมเพลต สามารถตั้งค่าหลายภาษาในชื่อเทมเพลตเดียวกันได้ ดังนั้นฟิลด์ name และ language ต้องใช้ร่วมกันเพื่อกำหนดเทมเพลตที่เลือกเมื่อส่ง |
components | components-object array | ไม่จำเป็น | เมื่อเทมเพลตมีตัวแปร ฟิลด์นี้ต้องกรอก ต้องตั้งค่าองค์ประกอบ components-object เพียงหนึ่งรายการในอาร์เรย์ |
คำอธิบายวัตถุ template.components
พารามิเตอร์ | ประเภท | ตัวเลือก | คำอธิบาย |
---|---|---|---|
type | String | จำเป็น | องค์ประกอบของเทมเพลต องค์ประกอบในเทมเพลตที่มีตัวแปรต้องกำหนดค่า ค่าเป็นไปได้: |
parameters | parameters object | จำเป็น | ตั้งค่าคอนเทนต์ของตัวแปร |
คำอธิบายวัตถุ template.components.parameters
พารามิเตอร์ | ประเภท | ตัวเลือก | คำอธิบาย |
---|---|---|---|
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 สอดคล้องกับรูปแบบ วัตถุภาพ |
video | video object | ไม่จำเป็น | ใช้เมื่อ type=video สอดคล้องกับรูปแบบ วัตถุวิดีโอ |
document | document object | ไม่จำเป็น | ใช้เมื่อ type=document สอดคล้องกับรูปแบบ วัตถุเอกสาร |
ตัวอย่าง
{
"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
}
}
]
}
]
}
}
}
หมายเหตุพิเศษสำหรับหมวดหมู่การยืนยันตัวตน
สำหรับข้อความเทมเพลตในหมวดหมู่การยืนยันตัวตน (เช่น หมวดหมู่คือ AUTHENTICATION) ตามกฎล่าสุดของ WhatsApp (2023/06/01) ฟิลด์เทมเพลตที่ส่งเมื่อสร้าง/แก้ไขเทมเพลตในหมวดหมู่การยืนยันตัวตนไม่สอดคล้องกับฟิลด์เทมเพลตสุดท้ายที่สร้างบนฝั่ง WhatsApp (ดูเอกสาร API สำหรับการสร้าง/แก้ไขเทมเพลตสำหรับรายละเอียดเพิ่มเติม) ดังนั้นสำหรับการส่งข้อความเทมเพลตในหมวดหมู่การยืนยันตัวตน นอกจากการส่งตัวแปรใน BODY แล้ว ยังต้องส่งตัวแปรใน BUTTON และค่าตัวแปรต้องสอดคล้องกัน
{
"from": "+8613800138000",
"to": [
"00447911123456"
],
"body": {
"type": "template",
"template": {
"name": "your-template-name",
"language": "zh_CN",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "123456"
}
]
},
// เพิ่มค่าตัวแปรปุ่ม โดยพื้นฐานแล้วปุ่มของเทมเพลตจะกลายเป็นประเภท URL ที่มีตัวแปร
{
"type": "button",
"sub_type": "url",
"index": 0,
"parameters": [
{
"type": "text",
"text": "123456"//ค่ารหัสเฉพาะของรหัสยืนยัน
}
]
}
]
}
}
}
พารามิเตอร์การตอบกลับ
การตอบกลับที่สำเร็จ
ฟิลด์ | ประเภท | ตัวเลือก | คำอธิบาย |
---|---|---|---|
message_id | String | จำเป็น | EngageLab WhatsApp message ID ระบุข้อความเฉพาะ |
request_id | String | ไม่จำเป็น | ID ที่กำหนดเองที่ส่งในคำขอ จะถูกส่งกลับในคำตอบตามที่เป็น |
{
"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"
}
รหัสข้อผิดพลาด
รหัสข้อผิดพลาด | รหัส HTTP | คำอธิบาย |
---|---|---|
1000 | 500 | ข้อผิดพลาดภายใน |
2001 | 401 | การรับรองความถูกต้องของ EngageLab ล้มเหลว ไม่มีการให้รูปแบบโทเค็นที่ถูกต้อง |
2002 | 401 | การรับรองความถูกต้องของ EngageLab ล้มเหลว โทเค็นหมดอายุหรือถูกปิดใช้งาน |
2003 | 400 | การรับรองความถูกต้องของ WhatsApp ล้มเหลว โปรดติดต่อฝ่ายสนับสนุนของ EngageLab |
2004 | 403 | ไม่มีสิทธิ์ในการเรียก API นี้ โปรดตรวจสอบว่า API key ได้รับอนุญาตสำหรับ API การส่งข้อความ (หมายเลขการส่งเฉพาะ) |
3001 | 400 | รูปแบบพารามิเตอร์คำขอไม่ถูกต้อง โปรดตรวจสอบว่าใช้รูปแบบ JSON |
3002 | 400 | ข้อผิดพลาดพารามิเตอร์คำขอ โปรดตรวจสอบว่าพารามิเตอร์คำขอตรงตามข้อกำหนด |
3003 | 400 | ข้อผิดพลาดพารามิเตอร์คำขอ การตรวจสอบทางธุรกิจที่เกี่ยวข้องล้มเหลว ดูคำอธิบายข้อผิดพลาดในฟิลด์ข้อความสำหรับรายละเอียด |
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 ในส่วน header |
100 MB |
sticker | image/webp | สติกเกอร์แบบคงที่: 100KB สติกเกอร์แบบเคลื่อนไหว: 500KB 512x512 พิกเซล |
รหัสภาษา
สำหรับความสัมพันธ์ระหว่างภาษาและรหัส โปรดดาวน์โหลดไฟล์นี้เพื่ออ้างอิง:
Template Language Codes.xlsx