Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

API kode disposisi

Disposition Codes API memungkinkan integrasi Anda melakukan hal berikut:

Mendapatkan daftar kode disposisi untuk instance, antrean, atau sesi.
Perbarui kode disposisi atau catatan (atau keduanya) untuk sesi panggilan atau chat yang telah diselesaikan sebelumnya.

Autentikasi dan URL dasar

Semua endpoint dalam dokumen ini menggunakan autentikasi token API standar menggunakan token pengguna API (token pembawa).

URL Dasar: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

Mendapatkan daftar kode disposisi

Dapatkan kode disposisi yang tersedia. Anda dapat membuat kueri di tingkat instance, antrean, dan sesi.

Menurut instance

Menampilkan hierarki kode disposisi lengkap untuk instance, termasuk semua kode disposisi multi-level.

Contoh permintaan

Permintaan berikut akan mendapatkan daftar lengkap kode disposisi:

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

Contoh respons

Contoh respons berikut menunjukkan daftar lengkap kode disposisi:

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

Menurut antrean

Menampilkan kode disposisi yang ditetapkan ke antrean. Jika tidak ada daftar khusus antrean yang dikonfigurasi, daftar global (tingkat instance) akan ditampilkan.

Contoh permintaan

Permintaan berikut akan mendapatkan kode disposisi untuk antrean:

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Parameter kueri

Parameter	Jenis	Wajib	Deskripsi
`queue_id`	integer	Ya	ID antrean untuk mendapatkan kode disposisi.

Menurut sesi

Menampilkan kode disposisi yang tersedia untuk ID sesi tertentu, berdasarkan antrean terakhir yang dilalui sesi tersebut.

Contoh permintaan

Permintaan berikut akan mendapatkan kode disposisi untuk sesi:

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Parameter kueri

Parameter	Jenis	Wajib	Deskripsi
`session_id`	integer	Ya	ID sesi.

Memperbarui kode dan catatan disposisi

Kirimkan kode atau catatan disposisi yang telah diperbarui (atau keduanya) untuk sesi panggilan atau chat yang telah diselesaikan sebelumnya. Tindakan ini akan membuat catatan disposisi dan catatan CRM baru. Fitur ini tidak mengedit data CRM asli.

Contoh permintaan

Permintaan berikut memperbarui kode disposisi atau catatan untuk sesi:

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

Parameter lokasi

Parameter	Jenis	Wajib	Deskripsi
`session_id`	integer	Ya	ID sesi panggilan atau chat yang akan diperbarui.

Contoh isi permintaan

Contoh berikut menunjukkan isi permintaan:

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

Parameter isi permintaan

Parameter	Jenis	Wajib	Deskripsi
`disposition_code`	objek	Kondisional	Kode disposisi yang diperbarui. Setidaknya salah satu dari `disposition_code` atau `notes` harus ada.
`disposition_code.id`	integer	Ya (jika `disposition_code` ditentukan)	ID kode disposisi.
`disposition_code.full_path`	string	Ya (jika `disposition_code` ditentukan)	Jalur hierarkis lengkap kode disposisi, misalnya, `/Support/Verification/Pending Documents`. Digunakan untuk validasi terhadap pohon disposisi sesi.
`notes`	string	Tidak	Catatan agen yang diperbarui. Lihat tabel Perilaku catatan.

Perilaku catatan

Nilai	Perilaku
Presentasikan dengan teks, misalnya, `"notes": "Updated notes"`	Mengganti catatan yang ada dengan teks baru.
Disajikan sebagai string kosong ("notes": "")	Menghapus catatan yang ada secara eksplisit. File metadata sesi tidak akan lagi berisi catatan. Histori CRM menyimpan catatan sebelumnya.
Dihilangkan (kolom tidak ada dalam permintaan)	Membiarkan catatan yang ada tidak berubah.

Disposisi jangan telepon (DNC)

Untuk mengirimkan disposisi "Jangan Telepon", gunakan disposition_code.id: -1. Ini hanya diterima jika instance mengaktifkan fitur jangan hubungi dan disposisi DNC dikonfigurasi. Jika tidak, API akan menampilkan 422 Unprocessable Entity dengan pesan: "Do Not Call disposition is not enabled for this tenant".

Atribusi agen

API tidak membawa identitas agen. Sistem mengatribusikan disposisi ke hal berikut, dalam urutan prioritas:

Agen yang awalnya mengirimkan disposisi untuk sesi ini.
Jika tidak ada disposisi asli, agen peserta terbaru dalam panggilan atau chat.

Jika keduanya tidak ada, API akan menampilkan 422 Unprocessable Entity.

Validasi

Daftar berikut menjelaskan aturan validasi:

Panggilan atau chat sesi harus telah berakhir. Mencoba memperbarui disposisi pada sesi aktif akan menampilkan 422 Unprocessable Entity.
Parameter disposition_code.id dan disposition_code.full_path divalidasi terhadap pohon disposisi sesi (berdasarkan antrean yang terakhir digunakan untuk merutekan sesi).
Setelan administrator allow_disposition_edit adalah kontrol khusus UI. API publik selalu dapat memperbarui data disposisi terlepas dari setelan ini.

Contoh respons

Contoh berikut menunjukkan respons terhadap permintaan yang berhasil:

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

Catatan: Kolom name diselesaikan oleh server dari pohon disposisi berdasarkan nilai id dan full_path yang ditentukan. Ini ditampilkan dalam respons untuk memudahkan.

Metadata sesi

Saat disposisi diperbarui menggunakan API ini, hal berikut akan terjadi:

Penyimpanan eksternal: File metadata sesi dibuat ulang dan menimpa file metadata yang ada.
CRM: Catatan baru dibuat, dengan mempertahankan jejak audit.

Penanganan error

Bagian ini menjelaskan penanganan error.

Kode status umum

Status	Kondisi	Contoh Pesan
`400 Bad Request`	Kolom wajib diisi tidak ada (`disposition_code` dan `notes` tidak ada), atau format tidak valid.	"Setidaknya salah satu dari disposition_code atau notes harus ada."
`401 Unauthorized`	Token API tidak valid atau tidak ada.	"Tidak sah"
`403 Forbidden`	Pengguna API tidak memiliki akses ke sesi atau tenant yang ditentukan.	"Dilarang"
`404 Not Found`	Sesi tidak ditemukan atau tidak ada.	"Sesi tidak ditemukan".
`422 Unprocessable Entity`	Berbagai kegagalan validasi. Lihat tabel 422 Unprocessable entity scenarios.	Lihat tabel 422 Unprocessable entity scenarios.

422 Skenario entitas yang tidak dapat diproses

Skenario	Pesan Error
Sesi panggilan atau chat masih aktif	"Sesi belum berakhir. Disposisi hanya dapat diperbarui untuk sesi yang telah selesai."
ID kode disposisi tidak ditemukan di hierarki sesi	"Kode disposisi tidak valid untuk antrean sesi ini."
Disposisi DNC dikirimkan, tetapi fitur tidak diaktifkan	"Disposition Jangan Telepon tidak diaktifkan untuk tenant ini".
Tidak ada peserta agen yang dapat diselesaikan untuk atribusi	"Tidak dapat menentukan agen untuk atribusi disposisi."

Contoh respons

Contoh berikut menunjukkan respons error:

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

Alur integrasi umum

Berikut adalah alur integrasi umum:

Mendapatkan kode disposisi untuk antrean atau sesi yang relevan:
- GET /api/v1/disposition_codes?session_id=SESSION_ID
Menampilkan pohon disposisi kepada pengguna atau sistem otomatis untuk dipilih.
Kirimkan disposisi yang telah diperbarui:
- POST /api/v1/sessions/SESSION_ID/disposition
- Sertakan disposition_code yang dipilih, dengan id dan full_path, serta catatan apa pun.
Menangani respons:
- Pada 200 OK: Disposisi telah diperbarui. Catatan CRM diperbarui secara otomatis.
- Jika terjadi error: Tampilkan pesan error dan coba lagi atau eskalasikan sebagaimana mestinya.

Perilaku CRM

Saat disposisi dikirim menggunakan API ini, hal berikut akan terjadi:

Catatan CRM baru dibuat di CRM yang terhubung, seperti Salesforce, ServiceNow, Zendesk, Dynamics, atau HubSpot. Catatan asli tidak diubah.
Untuk penyimpanan eksternal, file metadata sesi akan diganti dengan data disposisi yang diperbarui.

Batasan

Engagement panggilan HubSpot mencakup properti skalar hs_call_disposition yang ditimpa (tidak ditambahkan) pada setiap update disposisi. Meskipun histori lengkap dipertahankan dalam catatan HubSpot, properti engagement hanya mencerminkan kode disposisi terbaru.

API kode disposisi Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Autentikasi dan URL dasar

Mendapatkan daftar kode disposisi

Menurut instance

Menurut antrean

Menurut sesi

Memperbarui kode dan catatan disposisi

Perilaku catatan

Disposisi jangan telepon (DNC)

Atribusi agen

Validasi

Metadata sesi

Penanganan error

Kode status umum

422 Skenario entitas yang tidak dapat diproses

Alur integrasi umum

Perilaku CRM

Batasan

API kode disposisi