Obtenir les données de configuration utilisateur

L'API Apps est conçue pour récupérer les données de configuration des utilisateurs. Vous pouvez lire la configuration utilisateur actuelle pour tous les utilisateurs ou pour un seul utilisateur, quel que soit son rôle ou son état. Les rôles système et personnalisés sont inclus dans cette sortie.

Ce point de terminaison diffère de ceux utilisés dans le processus d'importation groupée d'utilisateurs et fournit les informations nécessaires pour prendre en charge les opérations groupées. Pour en savoir plus sur la gestion groupée des utilisateurs, consultez l'API Bulk User Management.

Fonctionnalités et limites de l'API

Lorsque vous récupérez des données utilisateur, vous pouvez inclure des paramètres pour adapter la réponse de l'API à vos besoins. Les paramètres suivants sont acceptés :

Utilisateur(s) spécifique(s)
- Options d'ID : adresse e-mail, ID système ou ID utilisateur personnalisé. Les utilisateurs peuvent spécifier un ou plusieurs ID. Si plusieurs ID utilisateur pointent vers le même utilisateur, celui-ci ne doit être représenté qu'une seule fois dans la réponse.
Pagination
- Les utilisateurs peuvent récupérer les résultats par ensembles paginés pour gérer les grands ensembles de données. La réponse de l'API doit indiquer s'il existe d'autres pages à récupérer.
- Un paramètre d'API permet aux utilisateurs de demander une page de résultats spécifique.
- Les utilisateurs peuvent spécifier la taille de la page. La taille de page par défaut est de 100 et la taille maximale est de 1 000. Lorsque vous indiquez un numéro de page spécifique, vous ne pouvez pas inclure d'ID utilisateur dans la demande.

La réponse de l'API inclut tous les champs de profil utilisateur et de configuration, à l'exception du champ "État". Au lieu du champ "État", l'API fournira un champ deactivated_at. Ce champ contient les éléments suivants :

Aucune valeur pour les utilisateurs actifs.
Date et heure de la désactivation d'un utilisateur.

Le tableau suivant liste les champs de profil utilisateur qui seront inclus dans la réponse de l'API :

Tableau 1. Tableau des champs de profil utilisateur

Order	Type de colonne	Nombre de colonnes	Nom de la ou des colonnes	Valeurs valides
1	E-mail	1	E-mail	E-mail
2	ID de l'agent	1	ID de l'agent	Chaîne
3	Prénom	1	Prénom	Chaîne
4	Nom	1	Nom	Chaîne
5	Alias	1	Alias	Chaîne
6	Désactivé le	1	Désactivé le	Aucune valeur, Date/heure
7	Emplacement	1	Emplacement	Chaîne correspondant à un nom de lieu, vide (aucune modification) ou nulle (supprimer le lieu actuel).
8	Conversation simultanée	1	Conversation simultanée	1 à X (où X est la valeur configurée), vide
9	État de la conversation simultanée	1	État de la conversation simultanée	0, 1, Vide
10	Appels internationaux non limités	1	Appels internationaux non limités	(Vrai/Faux)
11	Utilisateur externe	1	Utilisateur externe	(Oui/Non)
12	URI SIP externe	1	URI SIP externe	Chaîne
13	Nom d'utilisateur UCaaS	1	Nom d'utilisateur UCaaS	Chaîne
14	Extensions d'agent	1	Extensions d'agent
15	Rôles	Plusieurs	Rôle : Nom du rôle A Rôle : Nom du rôle B Rôle : Nom du rôle C, etc.	0, 1, Vide
16	Équipe	Plusieurs	Équipe : Équipe A, Équipe : Équipe B, Équipe : Équipe C, etc.	0, 1, Vide
17	Numéro de téléphone	Plusieurs	Numéro entrant direct : 1, Numéro d'arrivée directe : 2, Numéro d'arrivée directe : 3	Numéro de téléphone au format E. Format 164
18	Filtre	Unique	Filtre	Chaîne
19	Délai d'expiration du filtre	Unique	Délai d'expiration du filtre	Valeur numérique comprise entre 0 et 1 440

Limites

Un seul type d'ID utilisateur est accepté par requête.
Le nombre maximal d'ID par requête API est de 1 000.
Les utilisateurs ne peuvent pas fournir à la fois des ID utilisateur et une demande de numéro de page dans une même requête d'API. L'API renverra tous les utilisateurs en fonction de la requête, jusqu'à 1 000.

Messages d'erreur de l'API

L'API fournit les messages d'erreur suivants pour des scénarios spécifiques :

Taille de la page : "La taille de page maximale demandée a été dépassée (1 000 est la valeur maximale)"
Taille de page (nombre requis) : "Demande de taille de page non valide. La valeur doit être numérique."
Demande combinant un ID utilisateur et une pagination : "La combinaison d'un ID utilisateur et d'une demande de pagination n'est pas acceptée"
ID utilisateur (dépassement) : "Nombre maximal d'ID utilisateur dépassé (1 000 est le nombre maximal)"

Exemple de requête et de réponse

Cet exemple montre comment récupérer la première page d'utilisateurs avec 100 utilisateurs par page. Le corps de la réponse inclut un tableau d'objets utilisateur, chacun contenant des données de configuration utilisateur détaillées.

Requête :

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

Réponse :

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

Cet exemple montre comment récupérer les informations d'un seul utilisateur en transmettant un paramètre d'adresse e-mail. Le corps de la réponse inclut un objet utilisateur contenant des données de configuration utilisateur détaillées.