Panduan API platform chat

Halaman ini menunjukkan cara menggunakan endpoint chat seperti yang dijelaskan dalam Endpoint API platform chat.

Terminologi

Untuk memperjelas, berikut beberapa definisi yang penting untuk diingat saat menggunakan dokumen ini.

  • Pelanggan: Pelanggan Contact Center AI Platform (CCAI Platform) yang menerapkan API platform chat di software mereka.

  • Konsumen: Software yang membuat permintaan ke API platform chat.

  • Pengguna akhir: Pengguna software pelanggan yang mencoba melakukan chat dengan agen.

Autentikasi webhook

Chat platform API mengomunikasikan peristiwa yang terjadi selama percakapan kepada konsumen dengan mengirimkan permintaan webhook ke server konsumen. Payload dan jenis webhook ditentukan dalam spesifikasi API. Setiap permintaan webhook berisi dua header, X-Signature dan X-Signature-Timestamp.

X-Signature berisi tanda tangan webhook dengan format berikut: primary=<primary_signature> secondary=<secondary_signature>

Tanda tangan utama dan sekunder adalah digest sha256 berenkode base64 dari secret webhook utama atau sekunder, dengan string gabungan dari header X-Signature-Timestamp dan payload json permintaan.

Berikut adalah contoh penerapan otorisasi untuk permintaan webhook di aplikasi Ruby on Rails contoh:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Ringkasan

Secara umum, alur dasar percakapan API platform chat harus berjalan sebagai berikut. Poin-poin utama diberi nomor dan catatan disediakan untuk konteks tambahan. Perhatikan bahwa pelanggan hanya bertanggung jawab untuk menerapkan sisi "Pelanggan" dalam diagram, sementara Contact Center AI Platform menangani sisi sistem dan agen dalam diagram. Pencantuman mereka dalam diagram hanya dimaksudkan untuk memberikan konteks kepada pembaca tentang alur keseluruhan percakapan.

Alur percakapan API platform chat ditampilkan.

Membuat pengguna akhir

  • Chat memerlukan ID pengguna akhir yang valid saat dibuat, yang berarti pengguna akhir harus ada di sistem Contact Center AI Platform sebelum chat dibuat.

  • Pengguna akhir diidentifikasi secara unik berdasarkan atribut identifier mereka, yang merupakan nilai string yang diberikan oleh konsumen. Pengguna akhir mungkin sudah ada di sistem jika mereka telah menggunakan SDK web atau seluler. Endpoint POST /end_users diimplementasikan sebagai upsert idempoten, sehingga jika pengguna akhir sudah ada, mencoba membuatnya lagi akan memperbarui data yang berubah dan menampilkan informasi pengguna akhir.

Membuat percakapan

Untuk membuat percakapan menggunakan Chat Platform API, ikuti langkah-langkah berikut:

  1. Menangani payload chat baru: Proses inisialisasi chat terjadi secara asinkron dari permintaan POST /chats. Oleh karena itu, peristiwa chat_created dapat diterima sebelum atau setelah respons API dari endpoint pembuatan POST /chats. Sebaiknya tangani peristiwa chat_created dan respons API pembuatan chat dengan cara idempoten untuk menghindari bug di konsumen.

  2. Membuat percakapan dengan transkrip: API platform chat mendukung pembuatan percakapan dengan transkrip percakapan yang sudah ada, untuk skenario saat percakapan terjadi dalam platform pelanggan, misalnya, dengan chatbot, sebelum dikirim ke Contact Center AI Platform. Hal ini memberikan informasi tambahan tentang sesi chat kepada agen yang menjawab chat, dan membantu mencegah pengguna akhir mengulangi pertanyaan. Untuk format payload transkrip, lihat chat_platform_openapi.yaml.

Agen virtual pemilihan antrean

Untuk menyederhanakan pemilihan menu bagi konsumen API, API platform chat dirancang untuk digunakan bersama dengan agen virtual Dialogflow guna membantu penempatan dalam antrean untuk percakapan baru.

Langkah-langkah berikut harus dilakukan untuk menyiapkan agen virtual:

  1. Buat agen virtual khusus untuk tujuan ini, dan tetapkan ke antrean. Semua chat baru yang dibuat oleh API platform chat harus dibuat dalam antrean ini. Membuat dan mengonfigurasi agen virtual baru berada di luar cakupan dokumen ini.

  2. Saat membuat percakapan baru dengan endpoint POST atau chats, sertakan payload konteks kustom yang menyertakan beberapa konteks pada percakapan yang dibuat yang dapat digunakan agen virtual untuk menentukan antrean mana yang harus dituju percakapan tersebut. Payload konteks dapat berisi data kustom apa pun sebagaimana ditentukan oleh pelanggan, tetapi harus dalam format berikut agar data dapat diakses oleh agen virtual yang ditetapkan ke antrean.

    • Contoh: "context": {"value": {"foo": "bar" } } akan memungkinkan agen virtual membaca $session.params.context.foo dengan nilai bar.

  3. Dengan menggunakan data yang ada di kolom konteks, agen virtual (berdasarkan cara pelanggan mengonfigurasinya) akan mengeskalasikan chat ke antrean yang dipilih. Jika tidak ada agen yang tersedia dalam antrean target (seperti skenario saat antrean berada di luar jam kerja atau melebihi kapasitas), eskalasi akan dialihkan, dan konsumen akan menerima webhook yang menunjukkan alasan pengalihan dan opsi pengalihan yang tersedia.

Pengalihan eskalasi: Eskalasi chat di dukungan API platform chat opsi pengalihan berikut, jika dikonfigurasi di portal Contact Center AI Platform:

  • Email: Minta pengguna akhir mengirim email ke dukungan dan mengakhiri chat. Saat pengguna akhir memilih opsi ini, setelah email dikirim, pelanggan harus menandai percakapan sebagai dialihkan dan diakhiri menggunakan endpoint PATCH /chats/:id dengan parameter berikut di isi permintaan: "status": "finished" , "escalation_id": &lt;id of escalation> , dan "deflection_channel": "email"

  • Lanjutkan dengan agen virtual: Secara teknis, ini adalah opsi pengalihan yang valid, tetapi tidak masuk akal untuk menggunakan VA pemilihan antrean karena VA hanya akan mencoba mengeskalasikan percakapan lagi.

  • Terus menunggu agen manusia: Opsi ini hanya dapat digunakan untuk eskalasi dengan alasan over_capacity. Jika pengguna akhir memilih opsi ini, perbarui pengalihan eskalasi dengan PATCH chats/:id/escalations/:id with deflection_channel=human_agent

    • Link pengalihan eksternal: Memperingatkan pengguna akhir bahwa memilih link yang diberikan dalam pengalihan akan mengakhiri percakapan. Jika link dipilih, akhiri percakapan dan gunakan external_link untuk parameter deflection_channel

Mengirim dan menerima pesan

Untuk mengirim atau menerima pesan, ikuti langkah-langkah berikut:

  1. Konten teks: Untuk mengirim pesan teks, gunakan endpoint POST /chats/:id/message seperti yang ditentukan dalam dokumen API. Untuk menerima pesan, dengarkan peristiwa webhook message_received. Perhatikan bahwa konsumen API akan menerima peristiwa message_received untuk semua pesan yang dikirim menggunakan API, termasuk pesan yang dikirim oleh pengguna akhir.

  2. Konten Foto dan Video: Konten foto dan video dikirim dengan mengambil URL upload yang telah ditandatangani sebelumnya untuk layanan Cloud Storage yang dikonfigurasi dari Platform Contact Center AI, mengupload ke layanan penyimpanan, lalu mengirim URL penyimpanan dalam payload pesan ke Platform Contact Center AI.

    1. Mengambil URL yang telah ditandatangani: Ambil URL upload yang telah ditandatangani dari Contact Center AI Platform menggunakan POST /v1/chats/:chat_id/photos/upload atau POST /v1/chats/:chat_id/videos/upload endpoints. Endpoint ini menampilkan URL yang telah ditandatangani, beserta kumpulan kolom untuk diteruskan ke layanan penyimpanan saat mengupload file. Upload yang telah ditandatangani memiliki batasan berikut:

      • Content-Type adalah image/jpeg untuk foto, video/mp4 untuk video.

      • Ukuran foto maksimum adalah 2 MB. Ukuran video maksimum adalah 20 MB.

      • Waktu habis masa berlaku adalah 5 menit.

      • Klien harus mengubah ukuran dan menyesuaikan orientasi foto sebelum mengupload.

      • Setiap URL yang telah ditandatangani adalah untuk satu foto atau video - untuk mengirim beberapa lampiran, Anda harus meminta URL yang telah ditandatangani untuk setiap lampiran.

    2. Mengupload file media: Untuk mengupload file media, buat permintaan POST ke URL yang telah ditandatangani sebelumnya yang diambil di 2a dengan hal berikut di isi permintaan:

      • "file": file yang akan diupload

      • Semua kolom yang ditampilkan dalam objek kolom di permintaan URL yang telah ditandatangani sebelumnya.

    3. Menambahkan file media ke percakapan: Untuk menambahkan file media ke percakapan, gunakan endpoint POST /chats/:id/photos atau POST /chats/:id/videos. Perhatikan bahwa endpoint foto mendukung pengiriman array foto, sedangkan endpoint video hanya mendukung satu video dalam satu waktu.

      • Parameter isi permintaan s3_path harus memiliki nilai yang sama dengan kolom key dari respons URL yang telah ditandatangani sebelumnya.

      • Permintaan akan menampilkan dua kolom jika berhasil. Sebaiknya simpan atau simpan dalam cache pemetaan media_id ke URL di konsumen API, karena semua media dalam pesan chat hanya akan dirujuk oleh media_id.

        • url: URL S3 atau Cloud Storage hanya baca tempat file berada.

        • media_id: ID file media di Contact Center AI Platform. Ini adalah ID yang akan digunakan untuk merujuk media dalam payload chat.

    4. Mengirim file media sebagai pesan chat: Untuk mengirim file media sebagai pesan chat, kirim payload berikut ke POST /chats/:id/message endpoint:

    {
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}

Mengharapkan kunci JSON yang tidak dikenal dalam respons API

Semua update API kompatibel dengan versi sebelumnya. Kami berhak memperkenalkan kunci JSON baru dalam respons API yang ada kapan saja. Sebaiknya tangani respons secara defensif dengan mengabaikan kunci yang tidak dikenal untuk mempertahankan fungsi yang berkelanjutan.