API do agente do AWA

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 22 min. de leitura

    • A API do agente AWA (Advanced Work Assignment) fornece endpoints para gerenciar a presença do agente, a disponibilidade do canal e a carga de trabalho.

    Esta API requer o plug-in Atribuição avançada de trabalho (com.glide.awa) e a função awa_integration_user. Para obter mais informações, consulte Advanced Work Assignment.

    AWA Agente - GET /now/awa/agents/{user_id}

    Retorna o estado atual de presença do agente e a disponibilidade do canal.

    Formato da URL

    URL com controle de versões: /api/now/{api_version}/awa/agents/{user_id}

    URL padrão: /api/now/awa/agents/{user_id}

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    user_id Sys_id do item de trabalho listado na tabela Item de trabalho do AWA [awa_work_item].
    O item de trabalho deve atender aos seguintes critérios:
    • O item de trabalho deve ser atribuído ao agente especificado.
    • O item de trabalho deve estar no estado Aceitação pendente.

    Tipo de dados: cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Cabeçalho Descrição
    presença.canais.disponíveis Sinalizador que indica se o canal está disponível.
    Valores possíveis:
    • verdadeiro: o canal está disponível.
    • falso: o canal não está disponível.

    Tipo de dados: booliano
    presença.canais.sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    presença.sys_id sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].

    Tipo de dados: cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Tabela 7. Parâmetros do corpo da resposta (JSON ou XML)
    Parâmetro Descrição
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. Cada mensagem de erro tem uma descrição correspondente na propriedade detail.
    Valores possíveis:
    • Registro não encontrado: as informações fornecidas no corpo da solicitação são imprecisas ou não existem.
    • Usuário não autenticado: o usuário não tem a função awa_integration_user.

    Tipo de dados: cadeia de caracteres
    presença Informações sobre o estado de presença atual e o canal de um agente.

    Tipo de dados: objeto

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presença.disponível Sinalizador que indica se o agente está disponível.
    Valores possíveis:
    • verdadeiro: o agente está disponível.
    • falso: o agente não está disponível.

    Tipo de dados: booliano
    presença.canais Lista de objetos que descreve os canais de comunicação disponíveis com o agente.

    Tipo de dados: matriz

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "sys_id": "String"
 }
]
    presença.canais.disponíveis Sinalizador que indica se o canal está disponível.
    Valores possíveis:
    • verdadeiro: o canal está disponível.
    • falso: o canal não está disponível.

    Tipo de dados: booliano
    presence.channels.name Nome do canal, como Bate-papo ou Telefone.

    Tipo de dados: cadeia de caracteres
    presença.canais.restrict_update Sinalizador que indica se o usuário pode restringir atualizações, ou seja, selecionar o canal para disponibilidade.
    Valores possíveis:
    • verdadeiro: o usuário pode selecionar este canal para disponibilidade.
    • falso: o usuário não pode selecionar este canal para disponibilidade.

    Tipo de dados: booliano
    presença.canais.service_channel_type Tipo de canal de serviço, como bate-papo. Os valores possíveis variam de acordo com os plug-ins instalados.

    Tipo de dados: cadeia de caracteres
    presença.canais.sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    presence.name Nome do estado de presença do agente.
    Valores possíveis:
    • Disponível
    • Indisponível

    Tipo de dados: cadeia de caracteres
    presença.restrict_update Sinalizador que indica se o usuário pode restringir atualizações.
    Valores possíveis:
    • verdadeiro: o usuário pode restringir atualizações.
    • falso: o usuário não pode restringir atualizações.

    Tipo de dados: booliano
    presença.sys_id sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres
    sys_id sys_id do agente.

    Tipo de dados: cadeia de caracteres
    Item de trabalho

    workItem: informações sobre o item de trabalho associado ao evento.
    workItem.document workItem.document: Lista de documentos associados à tarefa de item de trabalho.
    workItem.document.sys_id workItem.document.sys_id: Sys_id do documento atribuído à tarefa de item de trabalho.
    workItem.document.table workItem.document.table: Nome da tabela de documentos atribuída à tarefa.
    workItem.previousWorkItem workItem.previousWorkItem: Sys_id do item de trabalho anterior para o mesmo ID de documento. Para os itens de trabalho de não transferência, este valor está vazio.
    workItem.serviceChannel workItem.serviceChannel: Lista de canais de serviço associados à tarefa de item de trabalho.
    workItem.serviceChannel.name workItem.serviceChannel.name: Nome do canal de serviço, como Bate-papo ou Telefone.
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: Sys_id do canal de serviço.
    workItem.size workItem.size: capacidade do agente usada quando este item de trabalho é atribuído ao agente.
    workItem.sys_id workItem.sys_id: Sys_id do item de trabalho que foi aceito ou oferecido.
    workItem.isQueueTransferred workItem.isQueueTransferred: indica se o item de trabalho foi transferido para a fila. Defina como verdadeiro se o item de trabalho for transferido da fila e falso se não for. Para obter mais informações sobre transferências de fila, consulte Transfer a chat to another queue.

    Amostra de solicitação cURL

    curl -X GET \
https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
    {
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

    AWA Agente - GET /now/awa/agents/{user_id}/capacities

    Retorna as capacidades do canal de um agente, a capacidade universal e a carga de trabalho atual para ver se o agente pode lidar com um caso.

    Use o método AWA Agente - PUT /now/awa/agents/{user_id}/capacities para modificar o canal e as capacidades universais de um agente.

    Consulte também:

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/awa/agents/{user_id}/capacities

    URL padrão: /api/now/awa/agents/{user_id}/capacities

    Parâmetros de solicitação compatíveis

    Tabela 8. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    user_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    Tabela 9. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 10. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 11. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 12. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 13. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    canais Lista de objetos que descreve os canais de comunicação disponíveis com o agente. 
    "channels": [
  {
    "channel_sys_id": "String",
    "current_workload": Number,
    "max_capacity": Number
  }
]

    Tipo de dados: matriz
    canais.channel_sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    canais.carga_de_trabalho_atual Número de itens de trabalho em um canal de serviço específico atualmente atribuído ao agente.

    Tipo de dados: número
    canais.max_capacity A carga de trabalho máxima em um canal de serviço específico ao qual o agente pode ser ativamente atribuído de cada vez.

    Tipo de dados: cadeia de caracteres
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. A descrição é fornecida na propriedade error.detail.

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres
    capacidade_universal Capacidade máxima para o agente em todos os canais de serviço. Se a carga de trabalho atual de um agente for igual à capacidade universal máxima, itens de trabalho adicionais não serão atribuídos ao agente.

    Esta propriedade só será retornada se houver um registro de capacidade universal para este agente.

    Tipo de dados: número
    carga_de_trabalho universal Número de itens de trabalho em todos os canais de serviço atualmente atribuídos ao agente especificado.

    Esta propriedade só retorna se houver um registro de capacidade universal para o agente.

    Tipo de dados: número

    Amostra de solicitação cURL

    O exemplo a seguir mostra como obter os valores de capacidade e carga de trabalho de um usuário.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Uma resposta bem-sucedida inclui valores de capacidade e carga de trabalho para cada canal.

    {
  "result": {
    "universal_workload": 2,
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "current_workload": 2,
        "max_capacity": 4
      }
    ],
    "universal_capacity": 10
  }
}

    AWA Agente - GET /now/awa/agents/{user_id}/presence_states

    Retorna os estados de presença de um agente e indica se o agente está disponível ou em outro estado de presença.

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/awa/agents/{user_id}/presence_states

    URL padrão: /api/now/awa/agents/{user_id}/presence_states

    Parâmetros de solicitação compatíveis

    Tabela 14. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    user_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    Tabela 15. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 16. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 17. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 18. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 19. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. A descrição é fornecida na propriedade error.detail.

    Tipo de dados: cadeia de caracteres
    <presence state> Lista de definições do estado de presença do agente como objetos. Cada objeto descreve o estado e inclui os canais do agente.

    Tipo de dados: matriz

    {
  "available": Boolean,
  "channels": [Array],
  "disable_inactivity_check": Boolean,
  "name": "String",
  "show_channels": Boolean,
  "sys_id": "String"
}
    <presence state>.disponível Sinalizador que indica se o agente está disponível.
    Valores possíveis:
    • verdadeiro: o agente está disponível.
    • falso: o agente não está disponível.

    Tipo de dados: booliano
    <presence state>.canais Lista de objetos que descreve os canais de comunicação disponíveis com o agente.

    Tipo de dados: matriz

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "restrict_update": Boolean,
  "service_channel_type": "String",
  "sys_id": "String"
 }
]
    <presence state>.canais.disponíveis Sinalizador que indica se o canal está disponível.
    Valores possíveis:
    • verdadeiro: o canal está disponível.
    • falso: o canal não está disponível.

    Tipo de dados: booliano
    <presence state>.canais.nome Nome do canal, como Bate-papo ou Telefone.

    Tipo de dados: cadeia de caracteres
    <presence state>.canais.sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    <presence state>.disable_inactivity_check Sinalizador que indica se deve ser verificado se há inatividade deste estado de presença.
    Valores válidos:
    • verdadeiro: a verificação de inatividade do estado de presença está desabilitada.
    • falso: a verificação de inatividade do estado de presença está habilitada.

    Tipo de dados: booliano

    Padrão: falso

    Para obter informações sobre como modificar essa configuração, consulte Configurar estados de presença do agente.
    <presence state>.nome Nome do estado de presença do agente. Os estados de presença instalados por padrão são Disponível, Ausentee Off-line .

    Tipo de dados: cadeia de caracteres
    <presence state>.ordem Ordem na qual esse estado é exibido na caixa de entrada do agente.

    Tipo de dados: número
    <presence state>.mostrar_canais Sinalizador que indica se o agente tem permissão para mudar o estado de presença, por exemplo, de disponível para ausente.
    Valores válidos:
    • verdadeiro: o usuário tem permissão para mudar a presença.
    • falso: o usuário está impedido de mudar a presença.

    Tipo de dados: booliano
    <presence state>.sys_id sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação cURL

    O exemplo a seguir mostra como obter os estados de presença de um agente especificado.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    O corpo da resposta lista os possíveis estados de presença do agente e indica que o agente está disponível.

    {
  "result": [
    {
      "name": "Available",
      "order": 0,
      "show_channels": false,
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3",
          "restrict_update": false,
          "service_channel_type": "chat"
        }
      ],
      "disable_inactivity_check": false
    },
    {
      "name": "Away",
      "order": 1000,
      "show_channels": false,
      "sys_id": "41f9b8dfb31313005baa6e5f26a8dcac",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    },
    {
      "name": "Offline",
      "order": 2000,
      "show_channels": false,
      "sys_id": "9cd83267575313005baaaa65ef94f98b",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    }
  ]
}

    AWA Agente - PUT /now/awa/agents/{user_id}

    Define o estado de presença de um agente especificado e, se fornecido, define a disponibilidade do canal do agente para esse estado.

    Formato da URL

    URL com controle de versões: /api/now/{api_version}/awa/agents/{user_id}

    URL padrão: /api/now/awa/agents/{user_id}

    Parâmetros de solicitação compatíveis

    Tabela 20. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    user_id Sys_id do agente. Localizado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    Tabela 21. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 22. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    presença.canais Lista de objetos que define quais canais estão disponíveis para o agente.
    Tipo de dados: matriz
    "channels": [
  { 
    "available": Boolean,
    "sys_id": "String"
  }
]
    presença.canais.disponíveis Sinalizador que indica se o canal está disponível.
    Valores possíveis:
    • verdadeiro: o canal está disponível.
    • falso: o canal não está disponível.
    Nota:
    Esta configuração deve ser especificada para incluir canais no corpo da resposta.

    Tipo de dados: booliano

    Padrão: falso
    presença.canais.sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    presença.sys_id sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].

    Tipo de dados: cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 23. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 24. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 25. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.
    Tabela 26. Parâmetros do corpo da resposta (JSON ou XML)
    Parâmetro Descrição
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. Cada mensagem de erro tem uma descrição correspondente na propriedade detail.
    Valores possíveis:
    • Registro não encontrado: as informações fornecidas no corpo da solicitação são imprecisas ou não existem.
    • Usuário não autenticado: o usuário não tem a função awa_integration_user.

    Tipo de dados: cadeia de caracteres
    presença Informações sobre o estado de presença atual e o canal de um agente.

    Tipo de dados: objeto

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presença.disponível Sinalizador que indica se o agente está disponível.
    Valores possíveis:
    • verdadeiro: o agente está disponível.
    • falso: o agente não está disponível.

    Tipo de dados: booliano
    presença.canais Lista de objetos que descreve os canais de comunicação disponíveis com o agente.

    Tipo de dados: matriz

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "sys_id": "String"
 }
]
    presença.canais.disponíveis Sinalizador que indica se o canal está disponível.
    Valores possíveis:
    • verdadeiro: o canal está disponível.
    • falso: o canal não está disponível.

    Tipo de dados: booliano
    presence.channels.name Nome do canal, como Bate-papo ou Telefone.

    Tipo de dados: cadeia de caracteres
    presença.canais.restrict_update Sinalizador que indica se o usuário pode restringir atualizações, ou seja, selecionar o canal para disponibilidade.
    Valores possíveis:
    • verdadeiro: o usuário pode selecionar este canal para disponibilidade.
    • falso: o usuário não pode selecionar este canal para disponibilidade.

    Tipo de dados: booliano
    presença.canais.service_channel_type Tipo de canal de serviço, como bate-papo. Os valores possíveis variam de acordo com os plug-ins instalados.

    Tipo de dados: cadeia de caracteres
    presença.canais.sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    presence.name Nome do estado de presença do agente.
    Valores possíveis:
    • Disponível
    • Indisponível

    Tipo de dados: cadeia de caracteres
    presença.restrict_update Sinalizador que indica se o usuário pode restringir atualizações.
    Valores possíveis:
    • verdadeiro: o usuário pode restringir atualizações.
    • falso: o usuário não pode restringir atualizações.

    Tipo de dados: booliano
    presença.sys_id sys_id do estado de presença. Localizado na tabela Estados de presença [awa_presence_state].

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres
    sys_id sys_id do agente.

    Tipo de dados: cadeia de caracteres
    Item de trabalho

    workItem: informações sobre o item de trabalho associado ao evento.
    workItem.document workItem.document: Lista de documentos associados à tarefa de item de trabalho.
    workItem.document.sys_id workItem.document.sys_id: Sys_id do documento atribuído à tarefa de item de trabalho.
    workItem.document.table workItem.document.table: Nome da tabela de documentos atribuída à tarefa.
    workItem.previousWorkItem workItem.previousWorkItem: Sys_id do item de trabalho anterior para o mesmo ID de documento. Para os itens de trabalho de não transferência, este valor está vazio.
    workItem.serviceChannel workItem.serviceChannel: Lista de canais de serviço associados à tarefa de item de trabalho.
    workItem.serviceChannel.name workItem.serviceChannel.name: Nome do canal de serviço, como Bate-papo ou Telefone.
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: Sys_id do canal de serviço.
    workItem.size workItem.size: capacidade do agente usada quando este item de trabalho é atribuído ao agente.
    workItem.sys_id workItem.sys_id: Sys_id do item de trabalho que foi aceito ou oferecido.
    workItem.isQueueTransferred workItem.isQueueTransferred: indica se o item de trabalho foi transferido para a fila. Defina como verdadeiro se o item de trabalho for transferido da fila e falso se não for. Para obter mais informações sobre transferências de fila, consulte Transfer a chat to another queue. 
    curl -X PUT \
 https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
-d '{"presence": {\
  "sys_id": "0b10223c57a313005baaaa65ef94f970",\
  "channels": [{ \
  "sys_id": "0bbdedbb3b892300a2bac9bb34efc445",\
  "available": true
}] 
}}
    {
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

    AWA Agente - PUT /now/awa/agents/{user_id}/capacities

    Habilita a atualização da capacidade máxima (carga de trabalho) de um agente para capacidades de canal e capacidade universal.

    Use o método AWA Agente - GET /now/awa/agents/{user_id}/capacities para recuperar o canal atual e as capacidades universais de um agente.

    Consulte também:

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/awa/agents/{user_id}/capacities

    URL padrão: /api/now/awa/agents/{user_id}/capacities

    Parâmetros de solicitação compatíveis

    Tabela 27. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: cadeia de caracteres
    user_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    Tabela 28. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 29. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    canais Obrigatório ao atualizar o valor máximo de um ou mais canais para o agente especificado. Objeto JSON que contém um ou mais pares de chave-valor que mapeiam o canal até sua capacidade máxima para cada canal atribuído ao agente.

    Tipo de dados: objeto

    O par está no seguinte formato:
    • Chave (sys_id do canal) – sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

      Tipo de dados: cadeia de caracteres

    • Valor (capacidade máxima) – A carga de trabalho máxima em um canal de serviço específico ao qual o agente pode ser ativamente atribuído de cada vez.

      Tipo de dados: número

    channels: {"<channel_sys_id>": <max_capacity>}
    capacidade_universal Obrigatório se a capacidade universal estiver sendo atualizada. Capacidade máxima para o agente em todos os canais de serviço. Se a carga de trabalho atual de um agente for igual à capacidade universal máxima, itens de trabalho adicionais não serão atribuídos ao agente.

    Tipo de dados: número

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 30. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 31. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 32. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    404 Não encontrado. O item solicitado não foi encontrado.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    canais Lista de objetos que descreve os canais de comunicação disponíveis com o agente. 
    "channels": [
  {
    "channel_sys_id": "String",
    "max_capacity": Number
  }
]

    Tipo de dados: matriz
    canais.channel_sys_id sys_id do canal. Localizado na tabela Canais de serviço [awa_service_channel].

    Tipo de dados: cadeia de caracteres
    canais.max_capacity A carga de trabalho máxima em um canal de serviço específico ao qual o agente pode ser ativamente atribuído de cada vez.

    Tipo de dados: cadeia de caracteres
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. A descrição é fornecida na propriedade error.detail.

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres
    capacidade_universal Capacidade máxima para o agente em todos os canais de serviço. Se a carga de trabalho atual de um agente for igual à capacidade universal máxima, itens de trabalho adicionais não serão atribuídos ao agente.

    Esta propriedade só será retornada se houver um registro de capacidade universal para este agente.

    Tipo de dados: número

    Amostra de solicitação cURL

    O exemplo a seguir mostra como alterar a capacidade universal do agente e a capacidade máxima de um canal especificado.

    curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"channels\": { \"27f675e3739713004a905ee515f6a7c3\": 6 },
 \"universal_capacity\" : 12
}" \
--user 'username':'password'

    Uma resposta bem-sucedida inclui os valores de capacidade atualizados.

    {
  "result": {
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "max_capacity": 6
      }
    ],
    "universal_capacity": 12
  }
}