SMS API

Dengan Contact Center AI Platform (CCAI Platform), Anda dapat menggunakan SMS API untuk menangani pesan SMS masuk dan keluar.

Autentikasi

Untuk menggunakan SMS API, Anda memerlukan kredensial.

Untuk membuat kredensial untuk SMS API, ikuti langkah-langkah berikut:

  1. Di portal Platform CCAI, klik Setelan > Setelan Developer > Pengelolaan kredensial API.

  2. Klik tombol + Add API Credential. Pesan Tambahkan Kredensial API akan terbuka.

  3. Masukkan Nama untuk Kredensial.

  4. Klik Create.

Outbound SMS API

Outbound SMS API menyediakan endpoint untuk memulai pesan SMS keluar. Dengan begitu, Anda dapat mengirim pesan SMS ke konsumen secara terprogram.

Ada tiga poin penting yang perlu dipertimbangkan saat menggunakan API ini:

  • Layanan ini tidak dirancang untuk mengirim puluhan ribu pesan sekaligus. Tujuannya adalah pesan berbasis peristiwa.

  • Konsumen dapat membalas pesan SMS dan memulai sesi dukungan.

  • API ini tidak akan berfungsi jika Anda perlu mengirim beberapa pesan SMS ke nomor yang sama dalam hari yang sama.

Kasus Penggunaan

Contoh kasus penggunaan Outbound SMS API berbasis peristiwa. Misalnya, jika Anda ingin memberi tahu konsumen bahwa pesanannya siap diambil DAN memberinya opsi untuk merespons. Sesi aktif dibuat saat SMS keluar dikirim; saat pelanggan merespons, ia akan diarahkan ke agen.

Perbedaan antara API ini dan SMS Keluar Tanpa Sesi adalah bahwa dengan tanpa sesi, Anda hanya mengirim notifikasi dan jika konsumen merespons, mereka akan menerima pesan default (jika dikonfigurasi) dan tidak dialihkan ke agen.

Kasus penggunaan potensial lainnya:

  • Login akun.
  • Aktivitas akun.
  • Peristiwa penggunaan akun yang penting.
  • Deteksi masalah perangkat terhubung.
  • Notifikasi ETA untuk layanan sesuai permintaan, seperti pengiriman dan transportasi online.
  • Pengingat janji temu.
  • Notifikasi proaktif terkait layanan atau akun.
  • Autentikasi dua faktor (memerlukan pelanggan memiliki generator kode dan proses layanan yang ada).

Endpoint API SMS keluar

URI dasar untuk endpoint baru ini adalah:

POST https://<subdomain>.<domain>/apps/api/v1/sms

Dukungan SMS masuk

Jika lingkungan ingin mendukung respons SMS masuk, nomor keluar juga perlu disiapkan sebagai nomor SMS masuk yang ditetapkan ke antrean. Setiap nomor telepon SMS hanya dapat ditetapkan ke satu antrean. Untuk mengetahui informasi selengkapnya, lihat: Konfigurasi Chat SMS Umum.

Jika pengguna akhir membalas SMS yang dikonfigurasi dengan cara ini, mereka akan diarahkan ke menu antrean SMS yang nomor telepon SMS masuknya ditetapkan. Untuk mengetahui informasi selengkapnya, lihat Setelan Chat Pesan SMS - Nomor Telepon.

Operasi API

Bagian ini menguraikan operasi API, parameter isi, dan kode respons.

Body dan Params

Kolom berikut harus disertakan dalam isi permintaan API:

Nama Kolom Jenis Wajib Deskripsi Nilai Catatan
agent_id Bilangan bulat Tidak Agen yang sesuai dengan ID ini akan ditetapkan ke percakapan baru jika tidak ada percakapan antara nomor yang diberikan. Jika agen terhubung ke percakapan yang sudah ada, pesan akan dikirim atas nama agen tersebut.
agent_email String Tidak Alamat email agen.
chat_type String Ya Pesan SMS SMSAP
chat_subtype String Ya api_initiated
end_user_number String Ya Nomor telepon yang akan dikirimi SMS Validasi: nomor telepon yang valid: +18882468888 untuk nomor telepon AS
outbound_number String Ya Nomor telepon keluar yang akan digunakan untuk mengirim pesan SMS Validasi: a) nomor telepon harus berupa nomor telepon SMS yang terkait dengan tenant, b) nomor telepon tidak ada, c) format nomor telepon salah: +18882468888 untuk nomor telepon AS
pesan String Ya Pesan SMS yang akan dikirim ke konsumen Pesan panjang: memecah pesan panjang menjadi beberapa pesan (harus tercakup dalam kemampuan SMS keluar yang ada) Validasi: a) pesan tidak ada, b) pesan melebihi jumlah karakter maksimum (sebanyak x)
ticket_id id Tidak Akan mengaitkan sesi dengan ID tiket CRM tertentu Catatan: ID tiket yang tidak valid akan diabaikan.

Error dan Berhasil

Kasus Hasil yang Diharapkan Salin
Layanan SMS diaktifkan
Layanan SMS keluar diaktifkan
Nilai chat_type adalah 'OutboundSMSAPI'
end_user_number diberikan dan diformat dengan benar
outbound_number diberikan dan diformat dengan benar
Untuk nomor telepon non-AS: nomor telepon non-AS diaktifkan
Pesan diberikan
Tidak ada chat aktif antara outbound_number dan end_user_number		 berhasil (200) Contoh Respons Berhasil
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
ID agen dan email agen diberikan error Hanya salah satu dari agent_id atau agent_email yang dapat diberikan.
ID agen atau email agen diberikan
Agen tidak terhubung ke percakapan yang ada		 error SMS keluar gagal. Agen tidak terhubung ke chat.
Layanan SMS tidak diaktifkan error "Layanan SMS tidak diaktifkan".
Layanan SMS keluar tidak diaktifkan error "Layanan SMS keluar tidak diaktifkan"
chat_type tidak diberikan error "chat_type needs to be provided" (chat_type harus diberikan)
chat_type disediakan tetapi tidak ditetapkan ke 'sms' error "Jenis chat yang valid harus diberikan"
end_user_number diberikan, tetapi tidak diformat dengan baik error "end_user_number is invalid"
(catatan: nomor telepon yang valid: "+18882468888" untuk nomor telepon AS)
end_user_number tidak diberikan error "end_user_number is required" (end_user_number wajib diisi)
outbound_number disediakan, tetapi tidak dibuat dengan baik error "outbound_number is invalid"
(catatan: nomor telepon yang valid: "+18882468888" untuk nomor telepon AS)
outbound_number diberikan, tetapi tidak ada untuk tenant tersebut error "outbound_number is not found" (outbound_number tidak ditemukan)
outbound_number tidak diberikan error "outbound_number is required" (outbound_number wajib diisi)
outbound_number adalah nomor telepon non-AS dan 'non US phone number service' tidak diaktifkan error "Layanan nomor telepon non-AS tidak diaktifkan"
Catatan: bergantung pada setelan Nomor telepon non-AS di Setelan > SMS Dalam Panggilan > Konfigurasi Nomor Telepon Non-AS
Pesan kosong error "pesan wajib diisi"
Chat aktif antara outbound_number dan end_user_number error "Outbound SMS failed. Konsumen sudah berada dalam sesi SMS aktif."
ticket_id diisi, tetapi tidak ada di CRM error "Tiket tidak ditemukan"

Masa berlaku SMS

Pesan SMS keluar akan aktif segera setelah dikirim.

Setiap chat SMS harus diakhiri sebelum sesi chat SMS baru dapat dibuat antara nomor telepon konsumen dan nomor telepon keluar tertentu. Hal ini mencakup pesan SMS keluar yang dikirim menggunakan API. SMS keluar akan gagal jika ada percakapan aktif yang sudah ada antara nomor telepon konsumen dan nomor telepon yang mengirim SMS keluar.

Opsi waktu tunggu chat otomatis

Opsi waktu tunggu chat otomatis dikonfigurasi di Setelan > Chat > Waktu Berakhir SMS & Waktu Tunggu Global. Hal ini memberikan kontrol untuk berapa lama sesi chat akan tetap aktif jika tidak ada aktivitas atau progres dalam alur sesi chat.

Perbedaan status chat

Berikut adalah perbedaan antara perubahan status proses chat:

  • Masa berlaku Chat status pemilihan antreanChat keluar yang dikirim menggunakan API dianggap dalam status pemilihan antrean hingga konsumen membalas

    Sesi chat yang belum melampaui status pemilihan antrean. Hal ini mencakup pesan SMS keluar yang dikirim dan belum dibalas oleh konsumen. Anda dapat menentukan berapa lama chat dapat tetap dalam status ini sebelum berakhir (pesan dikirim & konsumen tidak merespons dalam batas waktu - chat berakhir).

  • Masa berlaku chat SMS yang tidak terjawab (selama jam operasional)Lamanya waktu chat dapat tetap tidak terjawab dalam antrean sebelum masa berlakunya berakhir dalam jam operasional yang ditetapkan untuk antrean tertentu.

  • Masa berlaku chat SMS yang tidak terjawab (selama di luar jam kerja)Durasi waktu chat dapat tetap tidak terjawab dalam antrean sebelum masa berlakunya berakhir di luar jam kerja yang ditetapkan untuk antrean tertentu.

  • Waktu tunggu chat SMS keluar Sesi chat SMS keluar akan otomatis berakhir jika tidak ada aktivitas selama [x] menit.

Detail status chat

  • Saat SMS keluar dikirim menggunakan API, percakapan dianggap aktif, tetapi tidak terhubung

  • Chat SMS keluar yang aktif ini dianggap berada dalam status pemilihan antrean hingga konsumen membalas

  • Percakapan dianggap terhubung setelah konsumen membalas dan Agen ditetapkan ke percakapan

Dampak status chat pada timer yang diterapkan

  • Percakapan aktif yang dikirim menggunakan API yang belum mendapatkan respons dari konsumen tunduk pada timer status pemilihan Antrean

  • Chat yang terhubung ke agen tunduk pada timer habis masa berlaku Keluar

  • Jika konsumen membalas pesan awal, tetapi Agen tidak pernah ditugaskan, chat tidak terhubung dan tunduk pada timer berakhirnya Chat yang Tidak Terjawab, di dalam atau setelah jam operasional

Contoh alur dan status pesan API:

  1. Pesan SMS dikirim menggunakan API ke konsumen - chat dalam status pemilihan antrean dan tidak terhubung ke Agen

  2. Timer habis masa berlaku chat status pemilihan antrean dimulai. Chat akan berakhir dan berhenti jika konsumen tidak membalas dalam batas waktu timer.

  3. Konsumen membalas chat - chat kini terhubung ke Agen.

  4. Konsumen mengirim pesan terakhir - Timer waktu tunggu chat SMS keluar dimulai.

  5. Waktu tunggu chat SMS keluar telah mencapai batas - chat telah berakhir.

Tidak ada timer penutupan chat - untuk sesi SMS keluar yang dimulai API, timer penutupan chat tidak beroperasi sehingga peristiwa penutupan chat tidak akan terjadi meskipun setelah chat tersebut masuk sebagai chat masuk saat konsumen membalas pesan.

Definisi Respons

API merespons dengan satu objek panggilan, seperti yang terlihat dalam model dari /calls.

Sessionless Outbound SMS API

Platform CCAI menawarkan Outbound SMS API yang dapat mendukung pesan SMS keluar tanpa sesi tertaut.

Panggilan API ini memulai pesan SMS tertaut non-sesi yang dapat dipicu selama alur kerja yang ada menggunakan Platform CCAI.

SMS tanpa sesi lebih disukai jika hanya pesan satu kali yang dikirimkan kepada konsumen dan tidak perlu membuka tiket CRM.

Outbound SMS API ini memberikan kemampuan untuk mengirim hingga 500 pesan per panggilan API.

Kasus Penggunaan

Kasus penggunaan umum untuk SMS tanpa sesi dapat mencakup hal berikut:

  • Penyiapan sandi sekali pakai.

  • Kode verifikasi.

  • Pengingat janji temu.

  • Link masukan.

  • Pesan pemasaran atau promosi.

Sessionless Outbound API dan Outbound SMS API berbeda karena dengan Outbound SMS, saat konsumen merespons, sesi aktif akan dimulai dan mereka dapat diarahkan ke agen. Meskipun memiliki kasus penggunaan yang serupa (notifikasi pengiriman, pengingat janji temu), perbedaannya terletak pada apa yang terjadi saat konsumen merespons. Pengguna mungkin menerima notifikasi default jangan balas dengan tanpa sesi, tetapi dengan SMS keluar, pengguna akan diarahkan ke agen.

Endpoint API SMS keluar tanpa sesi

URI dasar untuk endpoint ini adalah:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

Menambahkan kredensial API

  1. Di portal Platform CCAI, buka Settings > Developer Settings > API Credential management.

  2. Klik tombol + Add API Credential. Pesan Tambahkan Kredensial API akan terbuka.

  3. Masukkan nama untuk kredensial Name.

  4. Klik Create.

Mengirim pesan SMS

Untuk mengirim SMS keluar tanpa sesi, panggil POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms dan teruskan parameter permintaan berikut:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Nama Kolom Jenis Wajib Deskripsi Catatan
from_phone String Ya Nomor telepon yang akan digunakan untuk mengirim pesan. Harus berupa nomor AS yang valid.
Panggilan API akan menampilkan error jika:
* nomor telepon bukan nomor telepon SMS yang terkait dengan tenant
* kolom from_phone kosong
* nomor telepon tidak mengikuti format yang benar. Misalnya, nomor berikut adalah nomor telepon AS yang valid: +18882468888
to_phones Array [String] Ya Nomor telepon yang akan dikirimi pesan. Untuk memastikan panggilan API berhasil:
* Pastikan Anda memiliki nomor telepon yang valid, seperti +18882468888
Jumlah maksimum nomor telepon adalah 100 per panggilan API.
pesan Array [String] Ya Pesan yang akan dikirim. Jumlah maksimum pesan terpisah yang dapat Anda kirim adalah 5.
Setiap pesan memiliki batas 320 karakter dan tidak boleh melebihi batas tersebut.

Respons API

Jika panggilan API berhasil, Anda akan melihat:

  • kode: 200

  • ID Permintaan

    Pastikan Anda mencatat ID permintaan dalam catatan sistem Anda. Jika Anda perlu memecahkan masalah, dukungan akan memerlukan ID permintaan untuk membantu.

Jika panggilan API gagal, Anda akan melihat:

  • kode: 4xx

  • Pesan error

Batasan SMS

  • API memproses maksimal 300 pesan per menit.

  • Semua pesan yang belum diproses akan berakhir dalam waktu 2 jam.