Nutzerkonfigurationsdaten abrufen

Die Apps API ist dafür konzipiert, Nutzerkonfigurationsdaten abzurufen. Sie können die aktuelle Nutzerkonfiguration für alle Nutzer oder für einen einzelnen Nutzer lesen, unabhängig von ihrer Rolle oder ihrem Status. Diese Ausgabe enthält sowohl System- als auch benutzerdefinierte Rollen.

Dieser Endpunkt unterscheidet sich von den Endpunkten, die beim Hochladen von Nutzern im Bulk verwendet werden, und enthält die erforderlichen Informationen für Bulk-Vorgänge. Weitere Informationen zum Ausführen von Bulk-Prozessen zur Nutzerverwaltung finden Sie unter Bulk User Management API.

API-Funktionen und ‑Einschränkungen

Beim Abrufen von Nutzerdaten können Sie Parameter einfügen, um die API-Antwort an Ihre Anforderungen anzupassen. Die folgenden Parameter werden unterstützt:

Bestimmte Nutzer
- ID-Optionen: E-Mail-Adresse, System-ID oder benutzerdefinierte Nutzer-ID. Nutzer können eine oder mehrere IDs angeben. Wenn mehrere Nutzer-IDs auf denselben Nutzer verweisen, sollte dieser Nutzer nur einmal in der Antwort dargestellt werden.
Seitenumbruch
- Nutzer können Ergebnisse in paginierten Sets abrufen, um große Datasets zu verwalten. Die API-Antwort sollte angeben, ob weitere Seiten abgerufen werden können.
- Mit einem API-Parameter können Nutzer eine bestimmte Seite mit Ergebnissen anfordern.
- Nutzer können die Seitengröße angeben. Die Standardseitengröße ist 100 und der Höchstwert ist 1.000. Wenn eine bestimmte Seitenzahl angegeben wird, können Nutzer-IDs nicht in die Anfrage aufgenommen werden.

Die API-Antwort enthält alle Nutzerprofil- und Konfigurationsfelder mit Ausnahme des Felds „Status“. Anstelle des Felds „Status“ wird in der API das Feld deactivated_at bereitgestellt. Dieses Feld enthält:

Kein Wert für aktive Nutzer.
Das Datum und die Uhrzeit, zu der ein Nutzer deaktiviert wurde.

In der folgenden Tabelle sind die Nutzerprofilfelder aufgeführt, die in der API-Antwort enthalten sind:

Tabelle 1. Tabelle „Nutzerprofilfelder“

Order	Spaltentyp	Anzahl der Spalten	Spaltenname(n)	Zulässige Werte
1	E-Mail	1	E-Mail	E-Mail
2	Agent-ID	1	Agent-ID	String
3	Vorname	1	Vorname	String
4	Nachname	1	Nachname	String
5	Alias	1	Alias	String
6	Deaktiviert am	1	Deaktiviert am	Kein Wert, Datum/Uhrzeit
7	Standort	1	Standort	Ein String, der ein Ortsname ist, leer (keine Änderung) oder null (aktuellen Ort entfernen).
8	Gleichzeitige Chats	1	Gleichzeitige Chats	1 bis X (wobei X der konfigurierte Wert ist), leer
9	Status der gleichzeitigen Chats	1	Status der gleichzeitigen Chats	0, 1, Leer
10	Internationale Anrufe ohne Einschränkungen	1	Internationale Anrufe ohne Einschränkungen	(Wahr/Falsch)
11	Externer Nutzer	1	Externer Nutzer	(Ja/Nein)
12	Externe SIP-URI	1	Externe SIP-URI	String
13	UCaaS-Nutzername	1	UCaaS-Nutzername	String
14	Agent-Erweiterungen	1	Agent-Erweiterungen
15	Rollen	Mehrere	Rolle: Rollenname A Rolle: Rollenname B Rolle: Rollenname C usw.	0, 1, Leer
16	Team	Mehrere	Team: Teamname A, Team: Teamname B, Team: Name des Teams C usw.	0, 1, Leer
17	Telefonnummer	Mehrere	Direkte eingehende Nummer: 1, Direkte eingehende Nummer: 2, Direkte eingehende Nummer: 3	Telefonnummer in E. E.164-Format
18	Filter	Einzelner	Filter	String
19	Filter-Timeout	Einzelner	Filter-Timeout	Numerischer Wert zwischen 0 und 1.440

Beschränkungen

Pro Anfrage wird nur ein Typ von Nutzer-ID unterstützt.
Die maximale Anzahl von IDs pro API-Anfrage beträgt 1.000.
Nutzer können nicht sowohl Nutzer-IDs als auch eine Seitennummeranfrage in einer einzigen API-Anfrage angeben. Die API gibt alle Nutzer basierend auf der Anfrage zurück, bis zu 1.000.

API-Fehlermeldungen

Die API gibt in bestimmten Szenarien die folgenden Fehlermeldungen zurück:

Seitengröße: „Maximale Seitengröße für Anfrage überschritten (maximal 1.000)“
Seitengröße (numerische Eingabe erforderlich): „Ungültige Anfrage für Seitengröße; muss ein numerischer Wert sein“
Kombinierte Nutzer-ID und Paginierungsanfrage: „Combination of user ID and pagination request is not supported“ (Die Kombination aus Nutzer-ID und Paginierungsanfrage wird nicht unterstützt)
Nutzer-ID (überschritten): „Maximale Anzahl von Nutzer-IDs überschritten (maximal 1.000)“

Beispiel für Anfrage und Antwort

In diesem Beispiel wird die erste Seite mit Nutzern mit 100 Nutzern pro Seite abgerufen. Der Antworttext enthält ein Array von Nutzerobjekten, die jeweils detaillierte Nutzerkonfigurationsdaten enthalten.

Anfrage

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

Antwort

[
  {
    "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"
    ]
  },
  ...
]

In diesem Beispiel wird gezeigt, wie Sie die Details eines einzelnen Nutzers abrufen, indem Sie einen E-Mail-Parameter übergeben. Der Antworttext enthält ein Nutzerobjekt mit detaillierten Nutzerkonfigurationsdaten.