Acessar dados de configuração do usuário

A API Apps foi projetada para recuperar dados de configuração do usuário. É possível ler a configuração atual de todos os usuários ou de um único usuário, independente da função ou do status. Funções do sistema e personalizadas estão incluídas nessa saída.

Esse endpoint é diferente dos usados no processo de upload de usuários em massa e fornece as informações necessárias para oferecer suporte a operações em massa. Para mais informações sobre como realizar processos de gerenciamento de usuários em massa, consulte a API Bulk User Management.

Recursos e limitações da API

Ao recuperar dados do usuário, é possível incluir parâmetros para personalizar a resposta da API de acordo com suas necessidades. Os seguintes parâmetros são compatíveis:

Usuários específicos
- Opções de ID: e-mail, ID do sistema ou ID do usuário personalizado. Os usuários podem especificar um ou vários IDs. Se vários User IDs apontarem para o mesmo usuário, ele só poderá ser representado uma vez na resposta.
Paginação
- Os usuários podem recuperar resultados em conjuntos paginados para gerenciar grandes conjuntos de dados. A resposta da API deve indicar se há mais páginas para recuperar.
- Um parâmetro de API permite que os usuários solicitem uma página específica de resultados.
- Os usuários podem especificar o tamanho da página. O tamanho de página padrão é 100, e o máximo é 1.000. Quando um número de página específico é fornecido, os IDs de usuário não podem ser incluídos na solicitação.

A resposta da API inclui todos os campos de perfil e configuração do usuário, exceto o campo "Status". Em vez do campo "Status", a API vai fornecer um campo deactivated_at. Esse campo vai conter:

Nenhum valor para usuários ativos.
A data e a hora em que um usuário foi desativado.

A tabela a seguir lista os campos do perfil de usuário que serão incluídos na resposta da API:

Tabela 1. Tabela de campos do perfil de usuário

Ordem	Tipo de coluna	Número de colunas	Nome das colunas	Valores válidos
1	E-mail	1	E-mail	E-mail
2	ID do agente	1	ID do agente	String
3	Nome	1	Nome	String
4	Sobrenome	1	Sobrenome	String
5	Alias	1	Alias	String
6	Desativado em	1	Desativado em	Nenhum valor, data/hora
7	Local	1	Local	Uma string que é um nome de local, Empty (sem mudança) ou Null (remover o local atual).
8	Concorrência de chat	1	Concorrência de chat	1 a X (em que X é o valor configurado), vazio
9	Status de simultaneidade do chat	1	Status de simultaneidade do chat	0, 1, vazio
10	Chamadas internacionais sem restrições	1	Chamadas internacionais sem restrições	(Verdadeiro/Falso)
11	Usuário externo	1	Usuário externo	(Sim/Não)
12	URI SIP externo	1	URI SIP externo	String
13	Nome de usuário do UCaaS	1	Nome de usuário do UCaaS	String
14	Extensões de agente	1	Extensões de agente
15	Papéis	Várias	Função: Nome da função A Função: Nome da função B Função: Nome da função C etc.	0, 1, vazio
16	Equipe	Várias	Equipe: Nome da equipe A, Equipe: Nome da equipe B, Equipe: Nome da equipe C etc.	0, 1, vazio
17	Número de telefone	Várias	Número de entrada direta: 1, Número de entrada direta: 2, Número de entrada direta: 3	Número de telefone em E. Formato 164
18	Filtro	Cluster único	Filtro	String
19	Tempo limite do filtro	Cluster único	Tempo limite do filtro	Valor numérico entre 0 e 1.440

Limitações

Apenas um tipo de ID de usuário é aceito por solicitação.
O número máximo de IDs por solicitação de API é 1.000.
Os usuários não podem fornecer IDs de usuário e um pedido de número de página em uma única solicitação de API. A API vai retornar todos os usuários com base na solicitação, até 1.000.

Mensagens de erro da API

A API vai fornecer as seguintes mensagens de erro para cenários específicos:

Tamanho da página: "Excedeu o tamanho máximo da página solicitado (o máximo é 1.000)"
Tamanho da página (requisito de entrada numérica): "Solicitação de tamanho de página inválida. Precisa ser um valor numérico"
ID do usuário combinado e solicitação de paginação: "A combinação de ID do usuário e solicitação de paginação não é aceita"
User-ID (excedido): "O número máximo de User-IDs foi excedido (o máximo é 1.000)"

Exemplo de solicitação e resposta

Este exemplo demonstra como recuperar a primeira página de usuários com 100 usuários por página. O corpo da resposta inclui uma matriz de objetos de usuário, cada um contendo dados detalhados de configuração do usuário.

Solicitação:

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

Resposta:

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

Este exemplo demonstra como recuperar os detalhes de um único usuário transmitindo um parâmetro de e-mail. O corpo da resposta inclui um objeto de usuário com dados detalhados de configuração do usuário.