Endpoint per la gestione collettiva degli utenti

Gli endpoint API di gestione collettiva consentono di creare o aggiornare un numero elevato di utenti tramite la raccolta di gestione collettiva degli utenti.

L'API supporta l'utilizzo di file JSON. Puoi ottenere dati JSON utilizzando l'API modello.

È supportata solo l'autenticazione api_user. Devi inserire il token utente API nella variabile password. L'autenticazione legacy che utilizza un secret aziendale non è supportata.

Quando viene caricato un file JSON tramite l'API di caricamento, viene creato un job e viene convalidato lo schema del file JSON.

Gli endpoint supportati per la gestione collettiva degli utenti includono:

Per eseguire l'aggiunta o gli aggiornamenti collettivi degli utenti utilizzando l'API per gli utenti collettivi, procedi nel seguente modo:

  1. Chiama il metodo Template per ottenere l'oggetto modello JSON che utilizzerai per generare il file JSON.

  2. Chiama il metodo Aggiungi utenti collettivamente da file o il metodo Aggiorna utenti collettivamente da file, a seconda che tu stia eseguendo un'aggiunta collettiva o un aggiornamento collettivo. Verifica lo schema del file JSON che fornisci.

  3. Dopo aver verificato lo schema del file JSON, chiama il metodo Proceed. In questo modo viene avviato il job.

  4. Per determinare lo stato del job, chiama il metodo Jobs.

Formato file JSON

Puoi ottenere il formato del file JSON chiamando il metodo del modello.

Nome del campo o dei campi Valori Obbligatorio Convalida
email String(Email) Sì Deve essere un'email valida. Deve essere univoco all'interno del file nella colonna Email (nessun duplicato), quindi solo un aggiornamento per indirizzo email per file
new_email String(Email) No Deve essere un'email valida. Deve essere univoco all'interno del file nella colonna Nuovo indirizzo email (nessun duplicato), quindi solo un aggiornamento per indirizzo email per file
agent_number Stringa No Una stringa senza convalida
first_name Stringa Sì Stringa non vuota
last_name Stringa Sì Stringa non vuota
stato Attivo, Non attivo, Vuoto No Deve essere "Attivo", "Non attivo" o vuoto
località Una stringa che è un nome di località, vuota o null No Deve corrispondere esattamente a una delle località esistenti (senza distinzione tra maiuscole e minuscole) o essere Null o vuoto
max_chat_limit Da 1 a X (dove X è il valore configurato), vuoto No Deve essere compreso tra 1 e X (incluso) o essere vuoto
max_chat_limit_enabled 0, 1, Vuoto No Deve essere 0, 1 o vuoto
ruoli name: Role name / value: 0, 1, Empty No Deve essere 0, 1 o vuoto
team name: Team name / value: 0, 1, Empty No Deve essere 0, 1 o vuoto

Una volta eseguito correttamente il metodo API di caricamento del file JSON, è possibile chiamare il metodo API Proceed e l'operazione di creazione o modifica dell'utente viene quindi elaborata.

I metodi di caricamento e procedi vengono eseguiti in modo asincrono da Contact Center AI Platform (CCAI Platform). Puoi controllare lo stato chiamando il metodo jobs e specificando job_id.

Campo Stato

Il campo status del job può avere uno dei seguenti valori:

Stato job Descrizione
creato Viene creato un job in attesa di convalida.
valid_scheme La convalida dello schema è riuscita ed è possibile procedere.
invalid_scheme Convalida dello schema non riuscita. È possibile controllare informazioni dettagliate tramite l'API Scheme error log.
in_progress Esecuzione della creazione/aggiornamento collettivo degli utenti.
completato Aggiornamento/creazione collettiva degli utenti completato.

Modello

Endpoint:

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

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Scarica modello

Questo esempio mostra come recuperare i modelli.

Richiesta

Body: None

Risposta: modello
[
    {
        "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
            }
        ]
    }
]

Codice di stato: 200

Job

Endpoint:

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

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Dettagli del job

Questo esempio mostra come recuperare i dettagli di un job specifico. In questo esempio, l'ID job è 1.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: dettagli del job
{
    "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": []
}

Codice di stato: 200

Elenco job

Questo esempio mostra come ottenere tutti i job.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
Risposta: elenco dei job
[
    {
        "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": []
    }
]

Codice di stato: 200

Job creato

Questo esempio mostra come recuperare i job di richiesta utente collettiva che sono stati creati.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: Job creato
{
    "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": []
}

Codice di stato: 200

Convalida del job riuscita

Questo esempio mostra come verificare che un job sia stato eseguito correttamente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: convalida della mansione riuscita
{
    "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": []
}

Codice di stato: 200

Convalida del job non riuscita

Questo esempio mostra come determinare che un job non è riuscito.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: la convalida del job non riesce
{
    "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": []
}

Codice di stato: 200

Aggiornamento del job

Questo esempio mostra come determinare che un job è in fase di aggiornamento.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: Aggiornamento del job
{
    "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": []
}

Codice di stato: 200

Aggiornamento del job completato senza errori

In questo esempio mostriamo come identificare un job completato senza errori.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: aggiornamento del job completato senza errori
{
    "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": []
}

Codice di stato: 200

Aggiornamento del job completato con errori

In questo esempio mostriamo come identificare un job completato con errori.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: Aggiornamento del job completato con errori
{
    "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"
    ]
}

Codice di stato: 200

Errore: ID job non valido

Questo esempio mostra una richiesta non riuscita in cui l'ID job non è valido.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Query:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
Risposta: Errore: ID job non valido
{
    "message": "Not Found"
}

Codice di stato: 404

Aggiungere e modificare utenti collettivamente da un file

Intestazioni:

Chiave Valore Descrizione
Content-Type multipart/form-data

Endpoint:

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

Corpo:

Chiave Valore Descrizione
file

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Job creato

Questo esempio mostra come inviare un job.

Richiesta

Corpo:

Chiave Valore Descrizione
file
Risposta: Job creato
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Codice di stato: 200

Procedi

Questo endpoint API viene utilizzato per continuare un job ipport che è stato avviato.

Endpoint:

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

Intestazioni:

Chiave Valore Descrizione
Content-Type multipart/form-data

Corpo:

Chiave Valore Descrizione
id `[job_id}`

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Procedi riuscito

Questo esempio mostra un'operazione di job riuscita.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type multipart/form-data

Query:

Chiave Valore Descrizione
id `[job_id}`
Response: Proceed success
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

Codice di stato: 200

Errore: procedi prima della convalida

Questo esempio mostra una procedura prima del completamento della convalida.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type multipart/form-data

Query:

Chiave Valore Descrizione
id `[job_id}`
Risposta: Errore: procedi prima della convalida
{
    "message": "This job cannot proceed update. status: created"
}

Codice di stato: 400

Errore: procedi quando è in corso

Questo esempio mostra una procedura quando il job è già in corso.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type multipart/form-data

Query:

Chiave Valore Descrizione
id `[job_id}`
Risposta: Errore: procedi quando è in corso
{
    "message": "Update is already in progress."
}

Codice di stato: 400

Errori dello schema

Endpoint:

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

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Errori dello schema

Questo esempio mostra come recuperare gli errori dello schema.

Richiesta

Body: None

Risposta: errori dello schema
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

Codice di stato: 200

Nessun errore

Questo esempio mostra come recuperare gli errori dello schema senza errori.

Richiesta

Body: None

Risposta: nessun errore
[]

Codice di stato: 200

Errori di aggiornamento

Endpoint:

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

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Errori di aggiornamento

Questo esempio mostra come recuperare gli errori dello schema con gli errori di aggiornamento.

Richiesta

Body: None

Risposta: errori di aggiornamento
[
    {
        "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"
    }
]

Codice di stato: 200

Nessun errore

Questo esempio mostra come recuperare gli errori dello schema senza errori.

Richiesta

Body: None

Risposta: nessun errore
[]

Codice di stato: 200