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

บทสนทนา

ขอดึงประวัติบทสนทนา

ขอประวัติที่เก่ากว่าเฉพาะแชทส่วนตัวของ provider=whatsapp ไม่รวม whatsapp-protocol โดย account_id ต้องเป็นส่วนพาธเดียวที่ไม่ว่าง ไม่มีช่องว่างหรือเครื่องหมายทับ รวมถึงแบบเข้ารหัส พาธไม่ถูกต้องคืน 400 invalid_request ให้สมัครรับ conversation.history ก่อน แบตช์ที่มีจะส่งแบบอะซิงโครนัสพร้อม data.history.source=on_demand ทั้ง HTTP 202 และ status=accepted หมายถึงรับคำขอเท่านั้น ไม่ใช่ได้รับข้อความหรือเสร็จสิ้น request_id ใช้ตรวจสอบปัญหา HTTP ไม่ใช่ ID งานและใช้เชื่อมโยงคอลแบ็กไม่ได้ อาจมีหลายแบตช์ ซ้ำ ล่าช้า หรือไม่มีคอลแบ็ก หากจะดึงต่อ ให้ใช้ข้อความเนื้อหาต้นฉบับที่เก่าที่สุดที่ได้รับและมี id, sent_at, direction ครบเป็น before โดยตัดบันทึกสังเคราะห์ type=call ออก และไม่เพิ่ม type ใน before ไม่มีเคอร์เซอร์หน้าถัดไปหรือสถานะเสร็จสิ้น แบตช์ว่าง จำนวนต่ำกว่า limit หรือหมดเวลาไม่ได้แปลว่าสิ้นสุดประวัติ คอลแบ็กอาจมาหลัง HTTP หมดเวลา จึงไม่ควรลองใหม่อัตโนมัติ 400 อาจคืน invalid_request, provider_invalid_request (รวมถึงจุดอ้างอิงจากบันทึกการโทรสังเคราะห์) หรือ unsupported_conversation_type สำหรับกลุ่มและช่อง ผู้ให้บริการอื่นคืน 501 unsupported_by_provider หากพาธบัญชีถูกต้องแต่ไม่มีบัญชีหรืออยู่นอกเวิร์กสเปซปัจจุบัน จะคืน 404 account_not_found (numeric_code=20020) ข้อผิดพลาดภายในที่ไม่ได้จัดประเภทคืน 500 request_conversation_history_failed (numeric_code=37016)

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/request

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

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

ที่มาของพารามิเตอร์
account_id
รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี

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

ส่วนหัว

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

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

Content-Type
stringจำเป็น

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

พารามิเตอร์ใน path

account_id
stringจำเป็น

ตัวระบุที่ใช้ใน route ของ conversations

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

conversation_id
stringจำเป็น

LID แชทส่วนตัวมาตรฐานของ WhatsApp ที่ตรงกับ ^[0-9]+@lid$ และต้องเป็นบทสนทนาเดียวกับ before ไม่รับหมายเลขโทรศัพท์หรือบทสนทนาประเภทอื่น

pattern: ^[0-9]+@lid$

before
objectจำเป็น

ตำแหน่งของข้อความเนื้อหาต้นฉบับหนึ่งข้อความในบทสนทนาเดียวกัน ทุกฟิลด์ต้องมาจากข้อความนั้นและห้ามเป็น null บันทึกการโทรสังเคราะห์ type=call ใช้ไม่ได้แม้มีครบทั้งสามฟิลด์ ห้ามใส่ type ในคำขอ

message_id
stringจำเป็น

id ของข้อความเนื้อหาต้นฉบับที่มีอักขระที่ไม่ใช่ช่องว่าง ID บันทึกการโทรสังเคราะห์ใช้ไม่ได้แม้ตัดช่องว่างหัวท้ายแล้ว ห้ามใช้ id ของเหตุการณ์ระดับบนสุดหรือ HTTP request_id แทน

minLength: 1 · pattern: \S

sent_at
stringจำเป็น

เวลาส่งของข้อความนั้นในรูปแบบ RFC3339 โดยวินาที Unix ต้องมากกว่า 0 ห้ามใช้ occurred_at ของเหตุการณ์หรือเวลาปัจจุบันแทน

format: date-time

direction
stringจำเป็น

ทิศทางข้อความเทียบกับบัญชีนี้: inbound คือรับ และ outbound คือส่ง

enum: inbound, outbound

limit
integer

จำนวนที่ร้องขอ ไม่รับประกันจำนวนที่ได้จริง ค่าเริ่มต้น 50 ใช้เฉพาะเมื่อละไว้เท่านั้น null, 0, ค่าที่ไม่ใช่จำนวนเต็ม หรือเกิน 50 จะคืน invalid_request ช่วงที่ใช้ได้คือ 1..50

minimum: 1 · maximum: 50

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

อ่านฟิลด์ตอบกลับและสถานะ HTTP ตามเอกสาร 204 สำเร็จไม่มีเนื้อหา ใช้ X-Request-Id เพื่อตรวจสอบ ขั้นตอนต่อไปอยู่ในการทำงานที่เกี่ยวข้อง

การตอบกลับ 202 Accepted

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "status": "accepted",
    "conversation_id": "100000000000002@lid",
    "limit": 50
  }
}

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

status
string

accepted confirms request acceptance only, not receipt of history or completion.

enum: accepted

conversation_id
string

Standard conversation ID for this history request.

limit
integer

Effective requested count limit for this history request, from 1 to 50.

minimum: 1 · maximum: 50

การตอบกลับ

202

202 Accepted

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

400

Bad Request

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

401

Unauthorized

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

404

Not Found

ไม่พบทรัพยากรของ provider ที่ร้องขอ

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 ยังใช้งานอยู่