Endpoint pengelolaan pengguna massal

Endpoint API pengelolaan massal memungkinkan Anda membuat atau memperbarui sejumlah besar pengguna melalui koleksi pengelolaan pengguna massal.

API ini mendukung penggunaan file JSON. Anda bisa mendapatkan data JSON menggunakan API template.

Hanya autentikasi api_user yang didukung. Anda harus memasukkan token pengguna API dalam variabel sandi. Autentikasi lama menggunakan rahasia perusahaan tidak didukung.

Saat file JSON diupload melalui upload API, tugas akan dibuat dan memvalidasi skema file JSON.

Endpoint yang didukung untuk pengelolaan pengguna massal meliputi:

Untuk melakukan penambahan atau pembaruan pengguna massal menggunakan API pengguna massal, lakukan hal berikut:

  1. Panggil metode Template untuk mendapatkan objek template JSON yang akan Anda gunakan untuk membuat file JSON.

  2. Panggil metode Tambahkan pengguna secara massal dari file atau Perbarui pengguna secara massal dari file, bergantung pada apakah Anda melakukan penambahan massal atau pembaruan massal. Tindakan ini memverifikasi skema file JSON yang Anda berikan.

  3. Setelah skema file JSON diverifikasi, panggil metode Proceed. Tindakan ini akan memulai tugas.

  4. Untuk menentukan status tugas, panggil metode Jobs.

Format file JSON

Anda bisa mendapatkan format file JSON dengan memanggil metode template.

Nama kolom Nilai Wajib Validasi
email String(Email) Ya Harus berupa email yang valid. Harus unik dalam file dalam kolom Email (tidak ada duplikat). Jadi, hanya ada 1 pembaruan per alamat email per file
new_email String(Email) Tidak Harus berupa email yang valid. Harus unik dalam file di kolom Email Baru (tidak ada duplikat). Jadi, hanya ada 1 pembaruan per alamat email per file
agent_number String Tidak String tanpa validasi
first_name String Ya String tidak kosong
last_name String Ya String tidak kosong
status Aktif, Tidak Aktif, Kosong Tidak Harus "Aktif", "Tidak aktif", atau kosong
lokasi String yang merupakan nama lokasi, Kosong, Null Tidak Harus sama persis dengan salah satu lokasi yang ada (tidak peka huruf besar/kecil), atau Null, atau kosong
max_chat_limit 1 hingga X (dengan X adalah nilai yang dikonfigurasi), Kosong Tidak Harus 1 hingga X (inklusif), atau kosong
max_chat_limit_enabled 0, 1, Kosong Tidak Harus 0, 1, atau kosong
roles name: Nama peran / value: 0, 1, Kosong Tidak Harus 0, 1, atau kosong
tim name: Nama tim / value: 0, 1, Kosong Tidak Harus 0, 1, atau kosong

Setelah metode API upload file JSON berhasil, metode API Lanjutkan dapat dipanggil, dan tugas pembuatan atau modifikasi pengguna akan diproses.

Metode upload dan lanjutkan dilakukan secara asinkron oleh Contact Center AI Platform (CCAI Platform). Anda dapat memeriksa status dengan memanggil metode jobs dan menentukan job_id.

Kolom status

Kolom status tugas dapat memiliki salah satu nilai berikut:

Status tugas Deskripsi
dibuat Tugas dibuat dan menunggu validasi.
valid_scheme Validasi skema berhasil dan proses dapat dilanjutkan.
invalid_scheme Validasi skema gagal. Informasi mendetail dapat diperiksa melalui Scheme error log API.
in_progress Melakukan pembuatan/pembaruan pengguna secara massal.
selesai Pembaruan/pembuatan pengguna massal selesai.

Template

Endpoint:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Mendapatkan template

Contoh ini menunjukkan cara mengambil template.

Permintaan

Isi: Tidak ada

Respons: Template
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

Kode Status: 200

Pekerjaan

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Detail tugas

Contoh ini menunjukkan cara mengambil detail tugas untuk tugas tertentu. Dalam contoh ini, ID tugas adalah 1.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Detail tugas
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Kode Status: 200

Daftar tugas

Contoh ini menunjukkan cara mendapatkan semua tugas.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Respons: Daftar tugas
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

Kode Status: 200

Lowongan dibuat

Contoh ini menunjukkan cara mengambil tugas permintaan pengguna massal yang telah dibuat.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Tugas dibuat
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Kode Status: 200

Validasi tugas berhasil

Contoh ini menunjukkan cara memvalidasi bahwa tugas berhasil.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Validasi tugas berhasil
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

Kode Status: 200

Validasi lowongan gagal

Contoh ini menunjukkan cara menentukan bahwa tugas telah gagal.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Validasi tugas gagal
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

Kode Status: 200

Memperbarui tugas

Contoh ini menunjukkan cara menentukan bahwa tugas sedang diperbarui.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Memperbarui tugas
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Kode Status: 200

Pembaruan lowongan selesai tanpa error

Dalam contoh ini, kami menunjukkan cara mengidentifikasi tugas yang selesai tanpa error.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Pembaruan tugas selesai tanpa error
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

Kode Status: 200

Pembaruan lowongan selesai dengan error

Dalam contoh ini, kami menunjukkan cara mengidentifikasi tugas yang telah selesai dengan error.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Pembaruan tugas selesai dengan error
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

Kode Status: 200

Error: ID tugas tidak valid

Contoh ini menunjukkan permintaan kegagalan saat ID tugas tidak valid.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type application/json

Kueri:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Respons: Error: ID tugas tidak valid
{
    "message": "Not Found"
}

Kode Status: 404

Menambahkan dan mengedit pengguna secara massal dari file

Header:

Kunci Nilai Deskripsi
Content-Type multipart/form-data

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

Isi:

Kunci Nilai Deskripsi
file

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Lowongan dibuat

Contoh ini menunjukkan cara mengirimkan tugas.

Permintaan

Isi:

Kunci Nilai Deskripsi
file
Respons: Tugas dibuat
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Kode Status: 200

Lanjutkan

Endpoint API ini digunakan untuk melanjutkan tugas ipport yang telah dimulai.

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

Header:

Kunci Nilai Deskripsi
Content-Type multipart/form-data

Isi:

Kunci Nilai Deskripsi
id `[job_id}`

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Berhasil melanjutkan

Contoh ini menunjukkan proses tugas yang berhasil.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type multipart/form-data

Kueri:

Kunci Nilai Deskripsi
id `[job_id}`
Respons: Berhasil diproses
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Kode Status: 200

Error: Lanjutkan sebelum validasi

Contoh ini menunjukkan proses sebelum validasi selesai.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type multipart/form-data

Kueri:

Kunci Nilai Deskripsi
id `[job_id}`
Respons: Error: Lanjutkan sebelum validasi
{
    "message": "This job cannot proceed update. status: created"
}

Kode Status: 400

Error: Lanjutkan saat sedang berlangsung

Contoh ini menunjukkan cara melanjutkan saat tugas sudah dalam proses.

Permintaan

Header:

Kunci Nilai Deskripsi
Content-Type multipart/form-data

Kueri:

Kunci Nilai Deskripsi
id `[job_id}`
Respons: Error: Lanjutkan saat sedang berlangsung
{
    "message": "Update is already in progress."
}

Kode Status: 400

Error skema

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Error skema

Contoh ini menunjukkan cara mengambil error skema.

Permintaan

Isi: Tidak ada

Respons: Error skema
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Kode Status: 200

Tidak ada error

Contoh ini menunjukkan cara mengambil error skema tanpa error.

Permintaan

Isi: Tidak ada

Respons: Tidak ada error
[]

Kode Status: 200

Error update

Endpoint:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

Contoh permintaan dan respons

Bagian berikut memberikan contoh permintaan ke endpoint.

Error update

Contoh ini menunjukkan cara mengambil error skema dengan error pembaruan.

Permintaan

Isi: Tidak ada

Respons: Error update
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

Kode Status: 200

Tidak ada error

Contoh ini menunjukkan cara mengambil error skema tanpa error.

Permintaan

Isi: Tidak ada

Respons: Tidak ada error
[]

Kode Status: 200