Recupero dei dati di configurazione utente

L'API Apps è progettata per recuperare i dati di configurazione dell'utente. Puoi leggere la configurazione utente attuale per tutti gli utenti o per un singolo utente, indipendentemente dal ruolo o dallo stato. In questo output sono inclusi sia i ruoli di sistema che quelli personalizzati.

Questo endpoint è diverso da quelli utilizzati nel processo di caricamento collettivo degli utenti e fornisce le informazioni necessarie per supportare le operazioni collettive. Per ulteriori informazioni su come eseguire le procedure di gestione collettiva degli utenti, consulta l'API Bulk User Management.

Funzionalità e limitazioni dell'API

Quando recuperi i dati utente, puoi includere parametri per personalizzare la risposta dell'API in base alle tue esigenze. Sono supportati i seguenti parametri:

Utenti specifici
- Opzioni ID: email, ID sistema o ID utente personalizzato. Gli utenti possono specificare uno o più ID. Se più ID utente rimandano allo stesso utente, quest'ultimo deve essere rappresentato una sola volta nella risposta.
Impaginazione
- Gli utenti possono recuperare i risultati in set paginati per gestire set di dati di grandi dimensioni. La risposta dell'API deve indicare se ci sono altre pagine da recuperare.
- Un parametro API consente agli utenti di richiedere una pagina specifica di risultati.
- Gli utenti possono specificare le dimensioni della pagina. La dimensione pagina predefinita è 100 e il valore massimo è 1000. Quando viene fornito un numero di pagina specifico, gli ID utente non possono essere inclusi nella richiesta.

La risposta dell'API include tutti i campi di configurazione e del profilo utente, ad eccezione del campo "Stato". Al posto del campo "Stato", l'API fornirà un campo deactivated_at. Questo campo conterrà:

Nessun valore per gli utenti attivi.
La data e l'ora in cui un utente è stato disattivato.

La seguente tabella elenca i campi del profilo utente che verranno inclusi nella risposta dell'API:

Tabella 1. Tabella dei campi del profilo utente

Ordine	Tipo di colonna	Numero di colonne	Nome colonna/e	Valori validi
1	Email	1	Email	Email
2	ID agente	1	ID agente	Stringa
3	Nome	1	Nome	Stringa
4	Cognome	1	Cognome	Stringa
5	Alias	1	Alias	Stringa
6	Disattivato alle ore	1	Disattivato alle ore	Nessun valore, Data/ora
7	Località	1	Località	Una stringa che è un nome di località, Empty (nessuna modifica), Null (rimuovi la posizione attuale).
8	Concorrenza della chat	1	Concorrenza della chat	Da 1 a X (dove X è il valore configurato), vuoto
9	Stato della concorrenza della chat	1	Stato della concorrenza della chat	0, 1, Vuoto
10	Chiamate internazionali non limitate	1	Chiamate internazionali non limitate	(Vero/Falso)
11	Utente esterno	1	Utente esterno	(Sì/No)
12	URI SIP esterno	1	URI SIP esterno	Stringa
13	Nome utente UCaaS	1	Nome utente UCaaS	Stringa
14	Estensioni dell'agente	1	Estensioni dell'agente
15	Ruoli	Multiplo	Ruolo: Nome ruolo A Ruolo: Nome ruolo B Ruolo: Nome ruolo C e così via.	0, 1, Vuoto
16	Team	Multiplo	Team: Nome team A, Team: Team Name B, Team: Team Name C ecc.	0, 1, Vuoto
17	Numero di telefono	Multiplo	Numero di chiamata diretta in entrata: 1, Numero di chiamata diretta in entrata: 2, Numero di selezione diretta: 3	Numero di telefono in formato Formato E.164
18	Filtro	Singolo	Filtro	Stringa
19	Timeout filtro	Singolo	Timeout filtro	Valore numerico compreso tra 0 e 1440

Limitazioni

È supportato un solo tipo di ID utente per richiesta.
Il numero massimo di ID per richiesta API è 1000.
Gli utenti non possono fornire sia ID utente sia una richiesta di numero di pagina in un'unica richiesta API. L'API restituirà tutti gli utenti in base alla richiesta, fino a 1000.

Messaggi di errore API

L'API fornirà i seguenti messaggi di errore per scenari specifici:

Dimensioni della pagina: "È stata superata la richiesta di dimensioni massime della pagina (1000 è il valore massimo)"
Dimensioni pagina (requisito di inserimento numerico): "Richiesta di dimensioni pagina non valida; deve essere un valore numerico"
Richiesta combinata di ID utente e paginazione: "La combinazione di ID utente e richiesta di paginazione non è supportata"
ID utente (superato): "È stato superato il numero massimo di ID utente (1000 è il massimo)"

Esempio di richiesta e risposta

Questo esempio mostra il recupero della prima pagina di utenti con 100 utenti per pagina. Il corpo della risposta include un array di oggetti utente, ognuno dei quali contiene dati di configurazione utente dettagliati.

Richiesta:

Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100

Risposta:

[
  {
    "email": "email",
    "agent_number": "number",
    "first_name": "first",
    "last_name": "last",
    "status": "Active",
    "location": "location",
    "max_chat_limt": 3,
    "max_chat_limit_enabled": true,
    "deleted_at": "2024-07-16T15:57:12.000Z",
    "ucaas_user_name": "username",
    "external_user": true,
    "ucaas_sip_uri": "sip uri",
    "unrestricted_international_calling": false,
    "roles": [
      { "name": "Admin" },
      { "name": "Manager" }
    ],
    "teams": [
      { "name": "name" }
    ],
    "phone_numbers": [
      "123-456-7890",
      "098-765-4321"
    ]
  },
  ...
]

Questo esempio mostra come recuperare i dettagli di un singolo utente passando un parametro email. Il corpo della risposta include un oggetto utente contenente dati di configurazione utente dettagliati.