AWA API de atribuição manual

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 7 min. de leitura

    • . Atribuição manual do AWA A API fornece um endpoint para atribuir manualmente itens de trabalho disponíveis a disponíveis Atribuição avançada de trabalho Agentes do (AWA).

    Um item de trabalho é um único trabalho tratado por um AWA agente do início ao fim. Por exemplo, um bate-papo ou um caso é um objeto que pode ser roteado e atribuído a agentes. Para obter mais informações, consulte Atribuição de trabalho avançada .

    Esta API requer Atribuição avançada de trabalho plug-in (com.glide.awa). Para chamar esta API, você deve ter a função awa_manager ou awa_integration_user.

    Atribuição manual do AWA - PUBLICAR /now/awa/workitems/

    Atribui um item de trabalho disponível a um disponível Atribuição avançada de trabalho Agente (AWA).

    O caso de uso primário deste endpoint é permitir que sistemas de roteamento externo roteiem itens de trabalho. Se Atribuição avançada de trabalho está configurado para usar roteamento externo, os itens de trabalho na fila são atribuídos usando roteamento externo e não AWA. Você pode atribuir a tarefa do item de trabalho chamando este endpoint. Para obter mais informações, consulte Usar roteamento externo .

    Formato de URL

    URL com controle de versão: /now/

    URL padrão: /now/awa/workitems/sys_id/assignments

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para REST APIs com script, há informações adicionais de versão no Formulário de serviço REST com script .

    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 acessado. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    work_item_sys_id Sys_id do item de trabalho a ser atribuído a um agente disponível.

    O item de trabalho deve ter atribuição cancelada e estar em Aceitação pendente ou Em fila estado. Para obter mais informações, consulte Verifique itens de trabalho de tarefa não atribuídos .

    Tipo de dados: Cadeia de caracteres

    Tabela: Itens de trabalho [awa_work_item]
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    after_timeout_presence Sys_id do estado de presença para o qual o agente alterna se for timeouto parâmetro expira.

    . timeouto parâmetro não foi passado, este parâmetro é ignorado.

    Para obter informações adicionais sobre estados de presença, consulte Configure agent presence states.

    Tipo de dados: Cadeia de caracteres

    Padrão: "" (cadeia de caracteres vazia)

    Tabela: Estado de presença do AWA [awa_presence_state]
    agent_sys_id Obrigatório. Sys_id do agente disponível para receber o item de trabalho. Os agentes são usuários com a função awa_agent.

    Para obter informações sobre como determinar se um agente está disponível, consulte Controles da caixa de entrada do agente .

    Tipo de dados: Cadeia de caracteres

    Tabela: Usuário [sys_user]
    allowed_to_recline Sinalizador que indica se os agentes têm permissão para rejeitar itens de trabalho. Se este parâmetro for verdadeiro , o cartão da caixa de entrada exibe ambos Aceitar e. Rejeitar botões no cartão da caixa de entrada.
    Valores válidos:
    • Verdadeiro/sim/1: O agente pode rejeitar itens de trabalho.
    • Falso/não/0: O agente não pode rejeitar itens de trabalho.

    Tipo de dados: Booliano

    Padrão: verdadeiro
    display_option Opção de exibição do cartão e da guia quando um item de trabalho é atribuído automaticamente.

    Este parâmetro só será válido se enable_auto_assignpassado como verdadeiro .

    Valores válidos:
    • Card_and_tab: Exibe o cartão e a guia.
    • Card_only: Exibe somente o cartão.

    Tipo de dados: Cadeia de caracteres

    Padrão: Card_only
    enable_auto_assign Sinalizador que indica se o item de trabalho deve ser aceito automaticamente ou deve permitir que o agente aceite ou rejeite manualmente o item de trabalho.
    Valores válidos:
    • True/yes/1: Aceitar automaticamente.
    • False/no/0: Permite que o agente aceite ou rejeite manualmente.

    Tipo de dados: Booliano

    Padrão: falso
    offered_on Tempo de oferta do item de trabalho. O tempo de oferta é usado para calcular o tempo restante que o agente deixou para aceitar o item de trabalho na caixa de entrada. Isso ajuda a considerar a discrepância entre o momento em que a solicitação de API é processada e quando o sistema de roteamento de terceiros invoca a solicitação de API. Este parâmetro permite que os sistemas externos que chamam este endpoint configurem o tempo de oferta do item de trabalho para que ele permaneça sincronizado com o acompanhamento interno do sistema externo do item de trabalho.

    Por exemplo, se o item de trabalho foi oferecido em 11:30:30, o tempo limite é de 30 segundos e a hora atual é 11:30:45, o temporizador de contagem regressiva exibe 00:15 (como em 15 segundos restantes).

    Este valor é armazenado no campo offered_on no item de trabalho.

    Este parâmetro será ignorado se timeouto parâmetro não foi passado.

    Tipo de dados: Cadeia de caracteres

    Formato: Carimbo de data/hora UTC (aaaa-MM-dd'T'HH:mm:ss.SSS)
    timeout Tempo que o item de trabalho permanece na caixa de entrada do agente aguardando que o agente aceite a atribuição de trabalho.

    Tipo de dados: Número

    Unidade: segundos

    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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou 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 possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    404 Não encontrado. O item solicitado não foi encontrado.
    409 Conflito. A solicitação não pôde ser aprovada devido a um erro com o item de trabalho ou o sys_id do agente fornecido.
    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
    êxito Sinalizador que indica se a atribuição manual do item de trabalho foi bem-sucedida.
    Valores possíveis:
    • Verdadeiro: Atribuição de item de trabalho bem-sucedida.
    • Falso: Falha na atribuição de item de trabalho.

    Tipo de dados: Booliano
    mensagem Mensagem de resposta confirmando atribuição bem-sucedida ou uma exceção.

    Sucesso: "Atribuição manual solicitada com sucesso."

    Exceções:
    • "O <work_item_sys_id> não é um item de trabalho válido" - o sys_id do item de trabalho fornecido não existe.
    • "<API_caller_sys_id> o solicitante não tem a função awa_manager ou awa_integration_user" - O usuário autenticado que faz a solicitação de API deve ter a função awa_manager ou awa_integration_user.
    • "<work_item_sys_id> o item de trabalho não pode ser atribuído" - O item de trabalho fornecido não pode ser atribuído porque está em Aceito ou Cancelado estado. Consulte Verifique itens de trabalho e eventos do AWA .
    • "O <agent_sys_id> não é um agente válido" - O agente não tem a função awa_agent.
    • "O item de trabalho já está atribuído ao <agent_sys_id>" - desde que o item de trabalho esteja atribuído a outro agente.
    • "O agente não está disponível" - O agente não está em Disponível AWA. Consulte Controles da caixa de entrada do agente .
    • "O valor do tempo limite não pode ser negativo" - O valor do tempo limite informado não pode ser negativo.
    • "<presence_state_sys_id> o estado de presença não é válido" - o sys_id do estado de presença fornecido não existe na tabela Estado de presença do AWA [awa_presence_state].
    • "A hora oferecida (<offered_on_timestamp>) deve estar no seguinte formato: aaaa-MM-dd'T'HH:mm:ss.SSS" – fornecido offered_ono carimbo de data/hora deve estar no formato especificado.
    • "O tempo oferecido (<offered_on_timestamp >) deve ser anterior à hora atual, caso contrário, o agente terá mais tempo para aceitar o item de trabalho" - fornecido offered_ono carimbo de data/hora não pode ser anterior à hora em que a solicitação é feita.
    • "O carimbo de data/hora após o tempo limite (<offered_on_timestamp >) deve ser posterior à hora atual, caso contrário, o agente não tem tempo para aceitar o item de trabalho" - o carimbo de data/hora após adicionar o valor de tempo limite ao fornecido offered_ono carimbo de data/hora deve ser posterior à hora em que a solicitação foi feita.
    • "O <display_option> não é uma opção de exibição válida" - display_option fornecido deve ser um dos seguintes valores: "Card_only" ou "card_and_tab"
    • "%s não é um valor booliano válido" - o valor do tipo booliano informado deve estar em um dos seguintes formatos boolianos: "sim"/"não", "verdadeiro"/"falso", "1"/"0"

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir mostra como atribuir um item de trabalho a um agente AWA disponível usando somente os parâmetros necessários.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"agent_sys_id\":\"<agent_sys_id>\"}" \
--user 'username':'password'

    O resultado mostra que a tarefa foi atribuída com sucesso ao agente. Você pode verificar os resultados no Atribuído a. Campo da tabela Itens de trabalho [awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}

    Solicitação de curl

    O exemplo a seguir mostra como atribuir um item de trabalho a um agente AWA disponível, incluindo os parâmetros opcionais.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
    "agent_sys_id": "46d44a23a9fe19810012d100cca80666",
    "timeout":"10",
    "offered_on":"2024-04-03T23:09:31.000"
  }'
--user 'username':'password'

    O resultado mostra que a tarefa foi atribuída com sucesso ao agente. Você pode verificar os resultados no Atribuído a. Campo da tabela Itens de trabalho [awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}