Cari Percakapan berdasarkan Pengidentifikasi Kontak

Sistem eksternal dapat mencari ID percakapan reguler yang terkait, waktu pembuatan, dan status saat ini untuk suatu kontak menggunakan pengidentifikasi bisnis, alamat email, atau nomor telepon lengkap kontak. ID percakapan yang dikembalikan dapat langsung digunakan dengan API V2 yang ada untuk mengambil detail percakapan, pesan, dan lainnya.

Metode Permintaan

GET

URL Permintaan

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

Autentikasi

API ini menggunakan autentikasi HTTP Basic. Sertakan Authorization di header permintaan, dengan API key sebagai nama pengguna dan API secret sebagai kata sandi. Proyek yang terkait dengan kredensial menentukan cakupan pencarian, sehingga Anda tidak perlu menyertakan ID proyek di path. Untuk detailnya, lihat Ikhtisar API.

Jika account_id disertakan dalam permintaan, nilainya harus sama dengan proyek yang terkait dengan kredensial; jika tidak, 401 akan dikembalikan.

Permintaan

Contoh Permintaan

              
              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)'

            

Saat mencari berdasarkan nomor telepon, + harus dienkode dalam URL:

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

            

Parameter Header Permintaan

Parameter Query

Aturan Pencocokan

• identifier: Peka terhadap huruf besar-kecil. Nilai asli dipertahankan, dan pencocokan substring atau wildcard tidak didukung.
• email: Spasi di awal dan akhir dihapus, lalu format email divalidasi sebelum dilakukan pencocokan tepat yang tidak peka terhadap huruf besar-kecil.
• phone: Spasi di awal dan akhir dihapus terlebih dahulu. Nomor harus lengkap, menyertakan + dan kode negara, serta sesuai dengan format phone_number kontak. API tidak menambahkan kode negara default atau mendukung pencocokan berdasarkan digit terakhir nomor.
• Parameter GET harus dienkode dengan benar di URL. Secara khusus, + dalam nomor telepon harus dienkode sebagai %2B.

Cakupan dan Pengurutan Pencarian

Kontak dan percakapan hanya dicari dalam proyek yang terkait dengan kredensial. API mengembalikan semua percakapan reguler yang terkait dengan kontak di seluruh inbox dalam proyek (conversation_category=chat), tidak termasuk percakapan tiket, dan tanpa memfilter berdasarkan agen, petugas yang ditugaskan, atau inbox saat ini.

Percakapan reguler dengan semua status akan dikembalikan: open, resolved, pending, snoozed, dan closed. API ini tidak menyediakan filter berdasarkan status; meskipun status diberikan, hasilnya tidak akan dipersempit.

Hasil diurutkan berdasarkan waktu pembuatan percakapan dalam urutan menurun. Jika waktu pembuatan sama, hasil diurutkan berdasarkan primary key percakapan internal dalam urutan menurun. Urutan paginasi tetap stabil selama data tidak berubah. Paginasi berbasis halaman tidak menjamin snapshot yang konsisten saat percakapan dibuat atau dihapus secara bersamaan.

Respons

Respons Berhasil

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
    }
  ]
}

            

Parameter Respons

Jika kontak tidak ada, kontak tidak memiliki percakapan reguler, atau halaman yang diminta melebihi jumlah total halaman, HTTP 200 akan tetap dikembalikan. Dalam ketiga kasus tersebut, payload adalah array kosong; meta.count tetap menyimpan jumlah total hasil yang sebenarnya.

Respons hanya berisi kolom yang tercantum di atas dan tidak mengembalikan pesan, lampiran, atau informasi pribadi kontak.

Respons Error

Respons error menggunakan struktur berikut. Deskripsi error tidak menampilkan nilai pencarian:

              
              {
  "error": "Error description"
}

            

Catatan Penggunaan

• API ini hanya menambahkan fungsi pencarian dan tidak mengubah data kontak atau percakapan.
• API tidak mendukung pencarian kontak dengan pencocokan fuzzy. Pastikan identifier, alamat email, atau nomor telepon yang disimpan oleh sistem eksternal sesuai dengan atribut kontak terkait di LiveDesk.
• Untuk memproses percakapan dalam hasil pencarian, gunakan payload[].id dari respons sebagai ID percakapan eksternal saat memanggil API V2 terkait.