ข้อความ

กล่าวถึง (@) สมาชิกในข้อความกลุ่ม

กล่าวถึง (@) สมาชิกกลุ่ม โดยระบุ ids ใน mentions และวาง {{@<id>}} ใน message.text หรือ caption WhatsApp รองรับข้อความและ caption ของสื่อ ส่วน LINE ปัจจุบันรองรับเฉพาะข้อความ Provider อื่นจะละเว้น mentions และ provider_data.mentions แบบเดิมเลิกใช้แล้ว

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

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

ใช้ 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 ผู้รับใหม่ต้องใช้กฎรหัสของช่องทางนั้น การรองรับการส่งข้อความแบบรวมศูนย์

คำขอ

curl -X POST "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "120363428346272482@g.us",
    "type": "group"
  },
  "message": {
    "type": "text",
    "text": "{{@8613912345678}} the report is ready."
  },
  "mentions": [
    { "id": "8600000000000@s.whatsapp.net" }
  ]
}'

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

ส่วนหัว

X-Api-Key

stringจำเป็น

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

Content-Type

stringจำเป็น

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

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

account_id

stringจำเป็น

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

minLength: 1

to

objectจำเป็น

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

id

stringจำเป็น

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

minLength: 1

type

stringจำเป็น

ประเภทผู้รับ: user, group หรือ channel

enum: user, group, channel

message

objectจำเป็น

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

type

stringจำเป็น

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

enum: text, image, video, audio, document, file, contact

text

string

ข้อความที่ไม่ว่างและต้องระบุเมื่อ message.type=text

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 ต้องมีแหล่งข้อมูลหนึ่งรายการ

minLength: 1

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

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

provider_data

object

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

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

reply_to

object

เป้าหมายของการตอบกลับแบบอ้างอิง ให้คัดลอก data.message.reply_token จาก webhook ขาเข้าไปยัง reply_to.reply_token ของคำขอส่งโดยไม่แก้ไข

reply_token

string

โทเค็นตอบกลับแบบทึบที่คัดลอกโดยไม่แก้ไขจาก data.message.reply_token ของ webhook ขาเข้า

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 — opaque reply handle ของ WhatsApp ที่อาจคืนเมื่อช่องทางมีตัวระบุข้อความที่ตอบกลับได้ และไม่ใช่ 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

opaque reply handle ของ WhatsApp ที่อาจคืนเมื่อช่องทางมีตัวระบุข้อความที่ตอบกลับได้ และไม่ใช่ id ข้อความแม่

การตอบกลับ

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: ตรวจฟิลด์บังคับ รูปแบบ และเงื่อนไขช่องทาง แล้วแก้คำขอ
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 เดิม ห้ามสร้างจากรหัสข้อความ ต้องใช้ช่องทางที่รองรับการตอบแบบอ้างอิง