Panduan API platform chat

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

Terminologi

Untuk kejelasan, 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

API platform chat mengomunikasikan peristiwa yang terjadi selama chat 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 ringkasan sha256 berenkode base64 dari rahasia webhook utama atau sekunder, dengan string gabungan dari header X-Signature-Timestamp dan payload json permintaan.

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

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 penting diberi nomor dan catatan diberikan untuk konteks tambahan. Perhatikan bahwa pelanggan hanya bertanggung jawab untuk menerapkan sisi "Pelanggan" diagram, sedangkan Contact Center AI Platform menangani sisi sistem dan agen kami dalam diagram. Pencantuman mereka dalam diagram hanya dimaksudkan untuk memberikan konteks kepada pembaca tentang alur chat secara keseluruhan.

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, yang merupakan nilai string yang disediakan 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 diubah dan menampilkan informasi pengguna akhir.

Membuat chat

Untuk membuat chat menggunakan API platform chat, 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 secara idempoten untuk menghindari bug di konsumen.

  2. Membuat chat dengan transkrip: API platform chat mendukung pembuatan chat dengan transkrip percakapan yang ada, untuk skenario saat chat terjadi dalam platform pelanggan, misalnya, dengan chatbot, sebelum dikirim ke Contact Center AI Platform. Hal ini memberikan informasi tambahan kepada agen yang menjawab chat tentang sesi chat, dan membantu mencegah pengguna akhir mengulang percakapan. 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 antrean untuk chat 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 chat baru dengan endpoint POST atau chats, sertakan payload konteks kustom yang menyertakan beberapa konteks tentang chat yang dibuat yang dapat digunakan agen virtual untuk menentukan antrean mana yang harus dirutekan ke chat. Payload konteks dapat berisi data kustom apa pun seperti yang 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 terdapat di kolom konteks, agen virtual (berdasarkan cara pelanggan mengonfigurasinya) akan meningkatkan chat ke antrean yang dipilih. Jika tidak ada agen yang tersedia di 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 API platform chat mendukung 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 chat sebagai dialihkan dan diakhiri dengan 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 meningkatkan chat lagi.

  • Terus tunggu 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: Peringatkan pengguna akhir bahwa memilih link yang disediakan dalam pengalihan akan mengakhiri chat. Jika link dipilih, akhiri chat 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 POST /chats/:id/message endpoint seperti yang ditentukan dalam dokumen API. Untuk menerima pesan, dengarkan message_received peristiwa webhook. 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 untuk layanan Cloud Storage yang dikonfigurasi dari Contact Center AI Platform, mengupload ke layanan penyimpanan, lalu mengirim URL penyimpanan dalam payload pesan ke Contact Center AI Platform.

    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 yang diambil di 2a dengan hal berikut di isi permintaan:

      • "file": file yang akan diupload

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

    3. Menambahkan file media ke chat: Untuk menambahkan file media ke chat, 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.

      • Permintaan akan menampilkan dua kolom jika berhasil. Sebaiknya simpan atau cache pemetaan media_id ke URL di konsumen API, karena semua media dalam pesan chat hanya akan direferensikan berdasarkan 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">,
    "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.