ค้นหาบทสนทนาตามตัวระบุผู้ติดต่อ

ระบบภายนอกสามารถค้นหา ID ของบทสนทนาปกติที่เชื่อมโยงกัน เวลาที่สร้าง และสถานะปัจจุบันของผู้ติดต่อได้ โดยใช้ตัวระบุทางธุรกิจของผู้ติดต่อ ที่อยู่อีเมล หรือหมายเลขโทรศัพท์แบบเต็ม ID บทสนทนาที่ส่งกลับมาสามารถนำไปใช้กับ V2 API ที่มีอยู่สำหรับรายละเอียดบทสนทนา ข้อความ และอื่น ๆ ได้โดยตรง

วิธีการร้องขอ

GET

URL คำขอ

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup

การยืนยันตัวตน

API นี้ใช้การยืนยันตัวตนแบบ HTTP Basic โดยส่ง Authorization ในส่วนหัวของคำขอ ใช้ API key เป็นชื่อผู้ใช้ และ API secret เป็นรหัสผ่าน โปรเจกต์ที่เชื่อมโยงกับข้อมูลรับรองจะกำหนดขอบเขตการค้นหา ดังนั้นจึงไม่จำเป็นต้องระบุ ID โปรเจกต์ใน path สำหรับรายละเอียด โปรดดู ภาพรวม API

หากมีการระบุ account_id ในคำขอ ค่านั้นจะต้องตรงกับโปรเจกต์ที่เชื่อมโยงกับข้อมูลรับรอง มิฉะนั้นระบบจะส่งคืน 401

คำขอ

ตัวอย่างคำขอ

curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

โค้ดนี้โชว์เป็นหน้าต่างลอย

เมื่อค้นหาด้วยหมายเลขโทรศัพท์ + จะต้องถูกเข้ารหัสแบบ URL:

GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

              
              GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

โค้ดนี้โชว์เป็นหน้าต่างลอย

พารามิเตอร์ส่วนหัวของคำขอ

Field	Type	Required	Description
`Authorization`	string	Yes	ยืนยันตัวตนโดยใช้ `Authorization: Basic base64(API Key:API Secret)` โดยเชื่อม API key และ API secret ด้วยเครื่องหมายโคลอน จากนั้นเข้ารหัสเป็น Base64

พารามิเตอร์ Query

Field	Type	Required	Description
`type`	string	Yes	ประเภทแอตทริบิวต์ที่ใช้ค้นหา อนุญาตเฉพาะ `identifier`, `email` และ `phone`
`value`	string	Yes	สตริงที่ต้องไม่ว่าง ซึ่งจะถูกจับคู่แบบตรงตัวกับแอตทริบิวต์ของผู้ติดต่อที่สอดคล้องกับ `type`
`page`	integer	No	จำนวนเต็มบวก ค่าเริ่มต้นคือ `1`
`page_size`	integer	No	จำนวนเต็มบวก ค่าเริ่มต้นคือ `20`; ค่าที่มากกว่า `50` จะถูกจำกัดเป็น `50`
`account_id`	integer	No	ID โปรเจกต์ โดยทั่วไปไม่จำเป็นต้องระบุ หากระบุ จะต้องตรงกับโปรเจกต์ที่เชื่อมโยงกับข้อมูลรับรอง มิฉะนั้นระบบจะส่งคืน `401`

กฎการจับคู่

identifier: คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ระบบจะคงค่าต้นฉบับไว้ และไม่รองรับการจับคู่แบบบางส่วนหรือ wildcard
email: ระบบจะลบช่องว่างด้านหน้าและด้านท้าย และตรวจสอบรูปแบบอีเมลก่อนทำการจับคู่แบบตรงตัว โดยไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
phone: ระบบจะลบช่องว่างด้านหน้าและด้านท้ายก่อน หมายเลขจะต้องสมบูรณ์ มี + และรหัสประเทศ และต้องตรงกับรูปแบบ phone_number ของผู้ติดต่อ API จะไม่เพิ่มรหัสประเทศเริ่มต้นให้ หรือรองรับการจับคู่จากเลขท้ายของหมายเลข
พารามิเตอร์ GET จะต้องถูกเข้ารหัสแบบ URL อย่างถูกต้อง โดยเฉพาะ + ในหมายเลขโทรศัพท์ควรถูกเข้ารหัสเป็น %2B

ขอบเขตการค้นหาและการจัดเรียง

ระบบจะค้นหาผู้ติดต่อและบทสนทนาเฉพาะภายในโปรเจกต์ที่เชื่อมโยงกับข้อมูลรับรองเท่านั้น API จะส่งคืนบทสนทนาปกติทั้งหมดที่เชื่อมโยงกับผู้ติดต่อในทุก inbox ของโปรเจกต์ (conversation_category=chat) โดยไม่รวมบทสนทนาแบบ ticket และไม่มีการกรองตามเอเจนต์ปัจจุบัน ผู้รับมอบหมาย หรือ inbox

ระบบจะส่งคืนบทสนทนาปกติทุกสถานะ ได้แก่ open, resolved, pending, snoozed และ closed API นี้ไม่รองรับการกรองตามสถานะ แม้ว่าจะมีการระบุ status ผลลัพธ์ก็จะไม่ถูกจำกัดให้แคบลง

ผลลัพธ์จะถูกจัดเรียงตามเวลาสร้างบทสนทนาจากใหม่ไปเก่า หากเวลาสร้างเหมือนกัน ผลลัพธ์จะถูกจัดเรียงตาม primary key ภายในของบทสนทนาในลำดับจากมากไปน้อย ลำดับการแบ่งหน้าจะคงที่ตราบใดที่ข้อมูลไม่เปลี่ยนแปลง การแบ่งหน้าแบบอิงหน้าไม่รับประกัน snapshot ที่สอดคล้องกันในระหว่างที่มีการสร้างหรือลบบทสนทนาพร้อมกัน

การตอบกลับ

การตอบกลับสำเร็จ

HTTP 200:

{ "meta": { "count": 2, "current_page": 1, "page_size": 20, "total_pages": 1 }, "payload": [ { "id": 202609000000002, "created_at": 1788739200, "status": "closed", "inbox_id": 12, "contact_id": 901 }, { "id": 202609000000001, "created_at": 1788652800, "status": "open", "inbox_id": 10, "contact_id": 901 } ] }

              
              {
  "meta": {
    "count": 2,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1
  },
  "payload": [
    {
      "id": 202609000000002,
      "created_at": 1788739200,
      "status": "closed",
      "inbox_id": 12,
      "contact_id": 901
    },
    {
      "id": 202609000000001,
      "created_at": 1788652800,
      "status": "open",
      "inbox_id": 10,
      "contact_id": 901
    }
  ]
}

โค้ดนี้โชว์เป็นหน้าต่างลอย

พารามิเตอร์การตอบกลับ

Field	Type	Description
`meta`	object	เมตาดาต้าการแบ่งหน้า
`meta.count`	integer	จำนวนรวมของบทสนทนาปกติที่ตรงกันทั้งหมด รวมทุกสถานะและไม่ได้รับผลกระทบจากการแบ่งหน้า
`meta.current_page`	integer	หมายเลขหน้าปัจจุบัน
`meta.page_size`	integer	จำนวนรายการจริงต่อหน้า; จะเป็น `50` เมื่อค่าที่ร้องขอมากกว่า `50`
`meta.total_pages`	integer	จำนวนหน้าทั้งหมด; จะเป็น `0` เมื่อไม่มีผลลัพธ์
`payload`	array	รายการบทสนทนาในหน้าปัจจุบัน
`payload[].id`	integer	ID บทสนทนาภายนอก หรือ `conversations.display_id`; สามารถนำไปใช้กับ V2 API ที่มีอยู่สำหรับรายละเอียดบทสนทนา ข้อความ และอื่น ๆ ได้โดยตรง
`payload[].created_at`	integer	เวลาที่สร้างบทสนทนาในรูปแบบ Unix timestamp หน่วยเป็นวินาที
`payload[].status`	string	สถานะปัจจุบันของบทสนทนา ซึ่งอาจเป็น `open`, `resolved`, `pending`, `snoozed` หรือ `closed`
`payload[].inbox_id`	integer	ID ของ inbox ที่เชื่อมโยง
`payload[].contact_id`	integer	ID ของผู้ติดต่อที่ตรงกัน

หากไม่มีผู้ติดต่อนี้อยู่ ผู้ติดต่อนี้ไม่มีบทสนทนาปกติ หรือหน้าที่ร้องขอเกินจำนวนหน้าทั้งหมด ระบบจะส่งคืน HTTP 200 ในทั้งสามกรณี โดย payload จะเป็นอาร์เรย์ว่าง และ meta.count จะยังคงแสดงจำนวนรวมจริงของผลลัพธ์เสมอ

การตอบกลับจะมีเฉพาะฟิลด์ที่ระบุไว้ข้างต้นเท่านั้น และจะไม่ส่งคืนข้อความ ไฟล์แนบ หรือข้อมูลติดต่อส่วนบุคคล

การตอบกลับเมื่อเกิดข้อผิดพลาด

การตอบกลับข้อผิดพลาดใช้โครงสร้างต่อไปนี้ โดยคำอธิบายข้อผิดพลาดจะไม่สะท้อนค่าที่ใช้ค้นหา:

{ "error": "Error description" }

              
              {
  "error": "Error description"
}

โค้ดนี้โชว์เป็นหน้าต่างลอย

HTTP Status Code	Scenario
`401`	ข้อมูลรับรองไม่ถูกต้อง ถูกปิดใช้งาน หรือหมดอายุ หรือ `account_id` ในคำขอไม่ตรงกับโปรเจกต์ที่เชื่อมโยงกับข้อมูลรับรอง
`409`	ข้อมูลย้อนหลังส่งผลให้มีผู้ติดต่อหลายรายที่ตรงกันภายในโปรเจกต์เดียวกัน API จะไม่เลือกผู้ติดต่อรายใดรายหนึ่งโดยพลการ ให้ใช้ `identifier` ที่ไม่ซ้ำกันเพื่อค้นหาแทน
`422`	ไม่มี `type` หรือ `type` ไม่รองรับ; ไม่มี `value`, `value` ว่าง ไม่ใช่สตริง หรือมีรูปแบบไม่ถูกต้อง; หรือพารามิเตอร์การแบ่งหน้าไม่ใช่จำนวนเต็มบวก

หมายเหตุการใช้งาน

API นี้เพิ่มเฉพาะความสามารถในการค้นหา และไม่ได้แก้ไขข้อมูลผู้ติดต่อหรือข้อมูลบทสนทนา
API ไม่รองรับการค้นหาผู้ติดต่อด้วยการจับคู่แบบคลุมเครือ โปรดตรวจสอบให้แน่ใจว่า identifier ที่อยู่อีเมล หรือหมายเลขโทรศัพท์ที่จัดเก็บโดยระบบภายนอก ตรงกับแอตทริบิวต์ของผู้ติดต่อที่เกี่ยวข้องใน LiveDesk
หากต้องการประมวลผลบทสนทนาในผลลัพธ์การค้นหา ให้ใช้ payload[].id จากการตอบกลับเป็น ID บทสนทนาภายนอกเมื่อเรียกใช้ V2 API ที่เกี่ยวข้อง