เอกสารอ้างอิง API

ข้อความ

ตอบกลับข้อความ (อ้างอิง)

ส่งการตอบกลับแบบอ้างอิง นำ reply_token จากอีเวนต์ขาเข้า message.received (data.message.reply_token) แล้วส่งกลับใน reply_to.reply_token โดยไม่แก้ไข — เป็น handle ที่เข้ารหัสแบบทึบ ห้ามสร้างหรือแก้เอง ปัจจุบันรองรับเฉพาะ WhatsApp: ผู้ให้บริการอื่นคืน 501 unsupported_by_provider ส่วน token ที่ถูกแก้ไขคืน 400 invalid_reply_token

POSThttps://api.unifyport.ai/v1/messages

ช่องทางที่รองรับ

WhatsApp

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ทำขั้นตอนยืนยันตัวตนให้เสร็จและตรวจสอบ runtime_status การยืนยันกับการเชื่อมต่อเป็นคนละสถานะ HTTP สำเร็จอย่างเดียวไม่ยืนยันความพร้อม

ที่มาของพารามิเตอร์
account_id
รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี
to.id · to.type
เมื่อตอบกลับให้คัดลอก data.conversation.id และ data.conversation.type จาก message.received ไปยัง to.id และ to.type ผู้รับใหม่ต้องใช้กฎรหัสของช่องทางนั้น การรองรับการส่งข้อความแบบรวมศูนย์

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key
stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

Content-Type
stringจำเป็น

ใช้ application/json เมื่อต้องส่งเนื้อหาของคำขอเป็น JSON

เนื้อหาของคำขอ

provider_data
object

ตัวเลือกการส่งเฉพาะ provider มีผลเฉพาะ provider และประเภทข้อความที่รองรับ seconds ของ WhatsApp audio/video ใช้จำนวนเต็มที่ไม่ติดลบ เฉพาะสำหรับ video ให้ใช้ค่า 0 ถึง 4294967295 และ waveform ใช้เฉพาะ audio หากรองรับการตอบกลับแบบอ้างอิงให้ใช้ reply_to ระดับบนสุด สำหรับ sticker ต้องละเว้น provider_data หรือใช้ออบเจ็กต์ว่าง ค่าที่ไม่ใช่ออบเจ็กต์คืน 400 invalid_request และออบเจ็กต์ที่ไม่ว่างคืน 400 provider_invalid_request

seconds
integer

ระยะเวลาแบบเลือกได้เป็นวินาทีสำหรับข้อความ WhatsApp audio และ video โดยใช้จำนวนเต็มที่ไม่ติดลบ เฉพาะสำหรับ video ค่าที่อนุญาตคือ 0 ถึง 4294967295

minimum: 0

waveform
string

ข้อมูล waveform แบบเลือกได้สำหรับข้อความ audio ของ WhatsApp ค่าที่ไม่ว่างต้องเข้ารหัสด้วย Base64 มาตรฐาน และเมื่อ decode แล้วต้องเป็นข้อมูล waveform แบบ JSON ที่ parse ได้ สตริงว่างจะถือว่าไม่ได้ระบุ ส่วนรูปแบบอื่นที่ไม่ถูกต้องจะส่งคืน HTTP 400 provider_invalid_request

account_id
stringจำเป็น

บัญชีของผู้ให้บริการที่ส่งข้อความ

minLength: 1

to
objectจำเป็น

ผู้รับ ประกอบด้วย id และ type

id
stringจำเป็น

ตัวระบุผู้รับฝั่ง provider

minLength: 1

type
stringจำเป็น

ประเภทบทสนทนามาตรฐาน: user, group หรือ channel กลุ่มประกาศของชุมชน WhatsApp ยังคงใช้ group

enum: user, group, channel

message
objectจำเป็น

payload ข้อความที่ปรับเป็นมาตรฐาน ข้อความตัวอักษรใช้ message.text สื่อใช้ message.url

type
stringจำเป็น

ประเภทข้อความ: text, image, video, audio, document, file, contact, link_preview, poll หรือ sticker

enum: text, image, video, audio, document, file, contact, link_preview, poll, sticker

text
string

เนื้อหาที่ไม่ว่างซึ่งจำเป็นสำหรับ text และ link_preview สำหรับ link_preview ต้องมีอักขระที่ไม่ใช่ช่องว่าง และ WhatsApp กำหนดให้มี link_preview.url ตรงตามต้นฉบับในเนื้อหาด้วย

minLength: 1

caption
string

คำบรรยายเสริมสำหรับข้อความ image, video, document หรือ file

url
string

URL HTTP(S) แบบ absolute ที่ไม่ว่าง โดย media ต้องมี url, file_url หรือ file_key

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_url
string

URL HTTP(S) สำรองแบบ absolute ที่ไม่ว่าง โดย media ต้องมีแหล่งข้อมูลหนึ่งรายการ

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_key
string

ข้อมูลอ้างอิงไฟล์ที่ไม่ว่าง โดย media ต้องมีแหล่งข้อมูลหนึ่งรายการ

contacts[]
object[]

อาร์เรย์นามบัตรที่ไม่ว่างและต้องระบุเมื่อ message.type=contact

minItems: 1

name
string

ชื่อที่แสดงที่ไม่ว่างและต้องมีในนามบัตรทุกรายการ

minLength: 1

phones[]
object[]

รายการหมายเลขโทรศัพท์ในนามบัตร

number
string

หมายเลขโทรศัพท์ ต้องมีใน phone ทุกรายการ

type
string

ป้ายกำกับโทรศัพท์ที่ไม่บังคับ เช่น CELL หรือ WORK

emails[]
object[]

รายการอีเมลในนามบัตร

address
string

ที่อยู่อีเมล ต้องมีใน email ทุกรายการ

format: email

type
string

ป้ายกำกับอีเมลที่ไม่บังคับ เช่น WORK หรือ HOME

organization
string

ชื่อองค์กรของผู้ติดต่อที่ไม่บังคับ

title
string

ตำแหน่งงานของผู้ติดต่อที่ไม่บังคับ

link_preview
object

ใช้เฉพาะ message.type=link_preview และต้องระบุพร้อม text ห้ามผสมกับ payload อื่น โครงสร้างกลางบังคับเฉพาะ url ส่วน title และ description เป็นตัวเลือกที่ใช้สตริงว่างได้แต่ห้าม null นโยบายส่งของ API นี้สำหรับ WhatsApp บังคับ title/image_url ที่ไม่ว่าง และจำกัด title ไม่เกิน 255 และ description ไม่เกิน 1024 อักขระ Unicode

url
string

ลิงก์ปลายทางที่ต้องระบุ เป็น URI แบบสัมบูรณ์ HTTP(S) ที่มีชื่อโฮสต์และไม่มีช่องว่าง ที่อยู่ในวงเล็บเหลี่ยมต้องเป็น IPv6 literal เท่านั้น เก็บค่าต้นฉบับและไม่รับประกันว่าจะเข้าถึงทรัพยากรได้

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

title
string

ชื่อพรีวิวแบบเลือกได้ ใช้สตริงว่างได้แต่ห้าม null สำหรับ WhatsApp ต้องไม่ว่างและยาวไม่เกิน 255 อักขระ Unicode

description
string

คำสรุปพรีวิวแบบเลือกได้ ใช้สตริงว่างได้แต่ห้าม null สำหรับ WhatsApp ยาวไม่เกิน 1024 อักขระ Unicode

image_url
string

URI รูปภาพแบบเลือกได้ แต่ WhatsApp บังคับให้ระบุและไม่ว่าง ต้องเป็น URI แบบสัมบูรณ์ HTTP(S) ที่มีชื่อโฮสต์และไม่มีช่องว่าง ที่อยู่ในวงเล็บเหลี่ยมต้องเป็น IPv6 literal เท่านั้น เก็บค่าต้นฉบับและไม่รับประกันว่าจะเข้าถึงทรัพยากรได้

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

poll
object

ต้องระบุและใช้เฉพาะ message.type=poll ห้ามผสมกับ text หรือ payload อื่น ต้องมี question, options และ max_selections โดยเก็บคำถามและชื่อตัวเลือกตามต้นฉบับ โครงสร้างกลางไม่จำกัดความยาวคำถาม จำนวนตัวเลือกสูงสุด หรือชื่อซ้ำ แต่ provider อาจมีข้อจำกัดเพิ่มเติม

question
string

คำถามโพลที่ต้องระบุ ต้องมีอักขระที่ไม่ใช่ช่องว่าง และเก็บตามต้นฉบับ

minLength: 1 · pattern: \S

options[]
object[]

อาร์เรย์ตัวเลือกที่ต้องระบุ ต้องมีอย่างน้อยสองตัวเลือกและแต่ละตัวต้องมี title

minItems: 2

title
string

ชื่อตัวเลือกที่ต้องระบุ ต้องมีอักขระที่ไม่ใช่ช่องว่าง ส่งโดยไม่ trim ไม่เปลี่ยนตัวพิมพ์หรือรูปแบบ Unicode

minLength: 1 · pattern: \S

max_selections
integer

ต้องระบุจำนวนตัวเลือกสูงสุดต่อผู้โหวต ไม่ใช่จำนวนผู้โหวต ต้องเป็นจำนวนเต็มตั้งแต่ 1 ถึงจำนวน options โดย API ตรวจสอบ ค่าจำนวนเต็มอย่าง 1.0 และ 1e0 เท่ากับ 1 ค่าที่ไม่ใช่จำนวนเต็มใช้ไม่ได้

minimum: 1

reply_to
object

เป้าหมายการตอบแบบอ้างอิง คัดลอก data.message.reply_token จากเหตุการณ์ข้อความที่อ้างอิงได้ หรือ data.reply_token จากผลการส่ง ไปยัง reply_to.reply_token ตามเดิม ใช้กับบัญชีและการสนทนาเดิม ห้ามแทนด้วย ID ข้อความ

reply_token
string

แฮนเดิลทึบจาก data.message.reply_token ของเหตุการณ์ข้อความที่อ้างอิงได้ หรือ data.reply_token ของผลการส่ง ใช้ค่าเดิมกับบัญชีและการสนทนาเดิม ห้ามแทนด้วย ID ข้อความ

minLength: 1

mentions[]
object[]

รายการเป้าหมาย @ ของข้อความกลุ่ม type=member ใช้ id สมาชิกของ Provider ที่สอดคล้องกัน ส่วน type=all หมายถึง @ทุกคน และมีผลเฉพาะเมื่อ Provider รองรับ มิฉะนั้นจะส่งคืน unsupported_message_type

type
string

ประเภทเป้าหมาย @ หากละไว้จะถือเป็น member เพื่อความเข้ากันได้กับคำขอเดิม type=member ต้องส่ง id ส่วน type=all ไม่ต้องส่ง id และใช้ได้เฉพาะแชตกลุ่ม

enum: member, all

id
string

ตัวระบุสมาชิก Provider ที่ต้องระบุเมื่อ type=member

minLength: 1

ทำความเข้าใจผลลัพธ์

เก็บ message_id และ provider_ref เพื่อเชื่อมโยงเหตุการณ์ภายหลังหรือตรวจสอบปัญหา accepted ไม่ได้แปลว่าส่งถึงแล้ว ยืนยันผ่านเหตุการณ์ตอบรับเฉพาะช่องทางที่รองรับ รูปแบบรหัสแตกต่างกันตามช่องทาง

reply_token — แฮนเดิลทึบที่ไม่ว่างของ WhatsApp อาจคืนหลังส่งสำเร็จเมื่อบริบทอ้างอิงครบ รวมถึงโพลที่เพิ่งส่งซึ่งข้อความธรรมดาใช้อ้างอิงได้ หากไม่มีจะละไว้โดยไม่เปลี่ยนสถานะ accepted ใช้ค่าเดิมกับบัญชีและการสนทนาเดิม ไม่ใช่ ID ข้อความ

การตอบกลับ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "message_id": "msg_example",
    "account_id": "acc_example",
    "status": "accepted",
    "provider_ref": "provider_msg_example",
    "reply_token": "<opaque WhatsApp reply handle>"
  }
}

เนื้อหาการตอบกลับ

message_id
string

ตัวระบุข้อความของ UnifyPort (msg_...) สำหรับข้อความที่ถูกรับไว้

account_id
string

บัญชีของผู้ให้บริการที่การตอบกลับนี้อ้างถึง

status
string

สถานะการรับ; accepted หมายถึงข้อความถูกเข้าคิวเพื่อนำส่งไปยังผู้ให้บริการ

provider_ref
string

reference ข้อความฝั่งผู้ให้บริการ เมื่อผู้ให้บริการกำหนดค่าให้แล้ว

reply_token
string

แฮนเดิลทึบที่ไม่ว่างของ WhatsApp อาจคืนหลังส่งสำเร็จเมื่อบริบทอ้างอิงครบ รวมถึงโพลที่เพิ่งส่งซึ่งข้อความธรรมดาใช้อ้างอิงได้ หากไม่มีจะละไว้โดยไม่เปลี่ยนสถานะ accepted ใช้ค่าเดิมกับบัญชีและการสนทนาเดิม ไม่ใช่ ID ข้อความ

minLength: 1

การตอบกลับ

200

200 OK

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

409

Conflict

การดำเนินการขัดแย้งกับบัญชีของผู้ให้บริการหรือทรัพยากรที่มีอยู่

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

501

Not Implemented

provider ที่เลือกยังไม่รองรับการดำเนินการนี้

502

Bad Gateway

อะแดปเตอร์หรือ upstream provider ไม่สามารถทำรายการให้เสร็จได้

เมื่อคำขอล้มเหลว

ตรวจ HTTP และ error.code/numeric_code เก็บ request_id แล้วแก้พารามิเตอร์ ยืนยันตัวตนต่อ หรือตรวจ runtime ตามสาเหตุ ตรวจผลครั้งก่อนก่อนส่งหรือเขียนซ้ำ อ้างอิงรหัสข้อผิดพลาด

invalid_request · 10000 · 400
ตรวจฟิลด์บังคับ รูปแบบ และเงื่อนไขช่องทาง แล้วแก้คำขอ
missing_api_key · 11000 · 401
ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่
invalid_api_key · 11001 · 401
ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่
provider_not_ready · 30009 · 409
กู้การยืนยันตัวตนและการเชื่อมต่อ แล้วตรวจผลครั้งก่อนก่อนลองใหม่
unsupported_message_type · 36000 · 400
เลือกการทำงานหรือชนิดข้อความที่รองรับ การส่งซ้ำไม่เพิ่มความสามารถ
invalid_reply_token · 36006 · 400
คัดลอก reply_token เดิม ห้ามสร้างจากรหัสข้อความ ต้องใช้ช่องทางที่รองรับการตอบแบบอ้างอิง