อัปเดต UnifyPort API: ป้ายกำกับการสนทนา ข้อความผู้ติดต่อ และการติดตาม Request — UnifyPort

สามสัปดาห์หลังจากรีลีส v1 เสถียร UnifyPort API ได้รับชุดฟีเจอร์แรก: ป้ายกำกับการสนทนาสำหรับจัดระเบียบแชท WhatsApp ประเภทข้อความนามบัตร การติดตาม request ทุกการเรียก API และชุดปรับปรุงประสบการณ์นักพัฒนาที่ทำให้เอกสารอ้างอิง webhook event มีประโยชน์มากขึ้นอย่างมาก

ด้านล่างนี้คือสิ่งที่อัปเดต พร้อมชื่อ endpoint และฟิลด์จริง

ป้ายกำกับการสนทนา — 4 endpoint ใหม่

ตอนนี้สามารถสร้าง แสดงรายการ อัปเดต และลบป้ายกำกับบนการสนทนา รวมถึงติดแท็กหรือถอดแท็กเป็นชุดได้ นี่คือระบบป้ายกำกับเดียวกับที่ WhatsApp ให้มาแบบ native — UnifyPort นำเสนอผ่านสี่ endpoint ภายใต้หมวด Conversations

แสดงรายการป้ายกำกับ

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

ส่งคืนรายการป้ายกำกับแบบแบ่งหน้า แต่ละป้ายมี id และ name:

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

สร้างหรืออัปเดตป้ายกำกับ

POST /v1/accounts/{account_id}/conversations/labels/upsert

label_id ว่างเปล่าเพื่อสร้างใหม่ ส่ง label_id ที่มีอยู่เพื่อเปลี่ยนชื่อ:

{
  "label_id": "",
  "name": "VIP"
}

ลบป้ายกำกับ

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

ติดแท็กหรือถอดแท็กบนการสนทนา

POST /v1/accounts/{account_id}/conversations/labels

action คือ add หรือ remove; conversation_ids ต้องมีอย่างน้อยหนึ่ง ID:

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

ทั้งสี่ endpoint รองรับเฉพาะ WhatsApp ในขณะนี้ Provider อื่นส่งคืน 501 unsupported_by_provider รหัสข้อผิดพลาดที่เกี่ยวข้อง — list_conversation_labels_failed, upsert_label_failed, delete_label_failed, set_label_members_failed — มีบันทึกไว้ในเอกสารอ้างอิงข้อผิดพลาด

ประเภทข้อความผู้ติดต่อ (vCard)

POST /v1/messages ตอนนี้รับ message.type: "contact" พร้อมอาร์เรย์ contacts แบบมีโครงสร้าง UnifyPort สร้าง vCard ให้อัตโนมัติ — คุณส่ง JSON แบบมีโครงสร้าง ผู้รับได้รับนามบัตรมาตรฐาน

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

แต่ละนามบัตรต้องมี name ฟิลด์ phones[].number, emails[].address, organization และ title เป็นทางเลือก สามารถส่งนามบัตรเดียวหรือหลายใบในอาร์เรย์ — WhatsApp จับคู่ใบเดียวกับประเภท contact และหลายใบกับ contact_array

อาร์เรย์ contacts ว่างหรือนามบัตรที่ขาด name ส่งคืน 400 invalid_request Provider ที่ไม่ใช่ WhatsApp ส่งคืน 400 unsupported_message_type จนกว่าจะเปิดให้รองรับ

การติดตาม Request — request_id และ X-Request-Id

ทุกการตอบกลับ API — ไม่ว่าสำเร็จหรือข้อผิดพลาด — ตอนนี้มีฟิลด์ request_id ระดับบนสุด และส่งคืนค่าเดียวกันผ่าน header ตอบกลับ X-Request-Id อ้างอิง ID นี้เมื่อรายงานปัญหาหรือ debug การเรียกที่ล้มเหลว

สำหรับการจับคู่ฝั่ง client ส่ง header request X-Request-Id ของคุณเอง แล้วมันจะถูก echo กลับเป็น client_request_id ในการตอบกลับ ช่วยให้คุณเชื่อมโยงการเรียก API ขาออกกับ request ID ภายในโดยไม่ต้องดูแลชั้นแมปปิ้งแยก

ตัวอย่าง payload webhook จริง

เอกสาร API ตอนนี้มีโครงสร้าง payload จริงจาก parser webhook อุปกรณ์ (Telegram และ WhatsApp)

message.received แสดง payload ตามประเภทเนื้อหา — ข้อความ รูปภาพ เสียง เอกสาร และตำแหน่ง — ให้คุณเห็นโครงสร้างฟิลด์ที่แม่นยำสำหรับแต่ละรูปแบบ แทนที่จะเดาจาก placeholder data: {} ว่างเปล่า

group.updated แสดง payload ตามประเภทการเปลี่ยนแปลง:

• เปลี่ยนชื่อ — changes[].kind: "renamed" พร้อม name กลุ่มใหม่
• เพิ่ม/ลบสมาชิก — changes[].kind: "member_added" หรือ "member_removed" พร้อมอาร์เรย์ members[] ของ ID สมาชิก
• เลื่อนขั้น/ลดขั้นแอดมิน — changes[].kind: "promoted" หรือ "demoted" พร้อม members[]

event group.updated เดียวสามารถมีหลายการเปลี่ยนแปลงพร้อมกัน — เช่น การเปลี่ยนชื่อพร้อมเพิ่มสมาชิกใน snapshot เดียวกัน

เครื่องมือใหม่สามตัวสำหรับนักพัฒนา

หน้าเครื่องมือเพิ่มยูทิลิตี้บนเบราว์เซอร์สามตัว ทั้งหมดทำงานฝั่ง client:

• ตัวสร้างลายเซ็น HMAC — สร้างและตรวจสอบลายเซ็น HMAC-SHA1/SHA256/SHA512 บนเบราว์เซอร์ มีประโยชน์เมื่อ debug การตรวจสอบ webhook signing_secret
• ตัวแปลง Unix Timestamp — แปลงไป-กลับระหว่าง Unix timestamp และวันที่อ่านได้ ตรวจจับวินาทีและมิลลิวินาทีอัตโนมัติ
• ตัวจัดรูปแบบ JSON — จัดรูปแบบ บีบอัด และตรวจสอบ JSON พร้อมไฮไลท์ไวยากรณ์และคัดลอก JSON Path คลิกเดียว

การเปลี่ยนแปลงที่กระทบ: ลบสองฟิลด์

สองฟิลด์ที่ยังไม่ได้ใช้งานถูกลบออกจากเอกสาร POST /v1/messages เพื่อให้ตรงกับ API surface จริง:

• idempotency_key — ลบแล้ว ฟิลด์นี้มีในเอกสารแต่ไม่เคยถูกใช้งานใน API อุปกรณ์
• provider_data.reply_to — ลบออกจาก surface เอกสาร ออบเจ็กต์ provider_data ตอนนี้แสดง parse_mode เป็นฟิลด์ตัวอย่าง

หากโค้ดของคุณส่ง idempotency_key หรือ provider_data.reply_to ให้ตรวจสอบว่าคุณพึ่งพาพฤติกรรมที่จริงๆ แล้วเป็น no-op หรือไม่ ทั้งสองฟิลด์ไม่ได้ถูก API ประมวลผล

ขั้นตอนต่อไป

ป้ายกำกับการสนทนาและข้อความผู้ติดต่อเปิดตัว WhatsApp ก่อน เพราะ API upstream ของ WhatsApp รองรับฟีเจอร์เหล่านี้แบบ native เมื่อ provider อื่นเพิ่มความสามารถเทียบเท่า — หรือเมื่อชั้นมาตรฐานสามารถเชื่อมช่องว่าง — ฟีเจอร์จะเปิดใช้บนช่องทางเพิ่มเติมด้วย endpoint surface เดียวกัน การตอบกลับ 501 unsupported_by_provider เป็นไปโดยตั้งใจ: มันบอกคุณอย่างแม่นยำว่า provider ไหนยังไม่รองรับฟีเจอร์ แทนที่จะเงียบๆ ทิ้ง request

เอกสาร API ฉบับสมบูรณ์อยู่ที่ unifyport.ai/docs