API de trabalho de oferta do AWA
A API de trabalho de oferta do AWA fornece um endpoint para atribuir ou transferir itens de trabalho para agentes.
Esta API deve ser usada com integrações de Central de contato como serviço (CCAAS) em que a decisão de roteamento e atribuição ocorre no sistema CCAAS externo. Esta API permite que um cartão de caixa de entrada seja mostrado a um agente no ServiceNow Espaço do agente como uma notificação para aceitar o item de trabalho.
Esta API requer o plug-in Atribuição avançada de trabalho (com.glide.awa). Para chamar esta API, você deve ter a função awa_manager ou awa_integration_user.
Para obter mais informações sobre AWA, consulte Advanced Work Assignment.
Trabalho de oferta do AWA – POST /now/awa/documents/{document_table}/{document_sys_id}/offer
Atribui ou transfere itens de trabalho para agentes.
Um item de trabalho é um único trabalho tratado por um agente AWA do início ao fim. Um item de trabalho é criado com base em um documento, como uma interação ou tarefa.
Todos os agentes que recebem ou transferem itens de trabalho com esta API devem ter as funções awa_agent e awa_external_user.
Formato da URL
URL com controle de versão: /api/now/{api_version}/awa/documents/{document_table}/{document_sys_id}/offer
URL padrão: /api/now/awa/documents/{document_table}/{document_sys_id}/offer
Parâmetros de solicitação compatíveis
| 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 |
| document_table | Nome da tabela associada ao documento, como a tabela Interação [interaction] ou Tarefa [task]. Tipo de dados: cadeia de caracteres |
| document_sys_id | Sys_id do documento a ser roteado para o agente ou para a fila. Tipo de dados: cadeia de caracteres |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
| Nome | Descrição |
|---|---|
| atribuição | Necessário para novas atribuições. Objeto que contém informações sobre a atribuição. Tipo de dados: objeto |
| atribuição.após_tempo_limite_presença | Sys_id do estado de presença para o qual o agente alterna se o parâmetro timeout expirar. Se o parâmetro timeout não for passado, este parâmetro será 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 (o estado de presença do agente não muda). Tabela: estado de presença do AWA [awa_presence_state] |
| atribuição.agent_sys_id | Necessário para novas atribuições. Sys_id do agente disponível para receber o item de trabalho. O agente deve ter as funções awa_agent e awa_external_user. 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] |
| atribuição.allowed_to_decline | 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 exibirá os botões Aceitar e Rejeitar no cartão da caixa de entrada.Valores válidos:
Tipo de dados: booliano Padrão: verdadeiro |
| atribuição.display_option | Opção de exibição para o cartão e a guia quando um item de trabalho é atribuído automaticamente. Este parâmetro só será válido se enable_auto_assign for verdadeiro. Valores válidos:
Tipo de dados: cadeia de caracteres Padrão: card_only |
| atribuição.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:
Tipo de dados: booliano Padrão: falso |
| atribuição.oferecido_em | Tempo de oferta do item de trabalho. O tempo de oferta é usado para calcular o tempo restante que o agente tem para aceitar o item de trabalho na caixa de entrada. Isso ajuda a contabilizar 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 sistemas externos que chamam este endpoint configurem o tempo de oferta do item de trabalho para que ele permaneça em sincronização 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 assigned_on no item de trabalho. Este parâmetro será ignorado se o parâmetro timeout não for passado. Tipo de dados: cadeia de caracteres Formato: carimbo de data/hora UTC (aaaa-MM-dd'T'HH:mm:ss.SSS) |
| atribuição.tempo limite | Quantidade de 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 Padrão: cadeia de caracteres vazia (sem limite de tempo). |
| external_segment_id | Identificador externo do sistema CCAAS do segmento de chamada oferecido ao agente. Tipo de dados: cadeia de caracteres |
| queue_id | Necessário para novas atribuições. Sys_id do registro de fila ou o identificador de fila em um sistema externo. Se estiver usando um queue_id de um sistema externo, ele deverá ser mapeado para o campo ID da fila do provedor (external_id) no registro awa_queue. Tipo de dados: cadeia de caracteres Tabela: fila [awa_queue] |
| transferência | Necessário para atribuições de transferência. Objeto que contém informações sobre a transferência. Se um valor for fornecido para este parâmetro, a atribuição será considerada uma atribuição de transferência. Tipo de dados: objeto |
| transfer.source_queue_id | Necessário para atribuições de transferência. Fila de origem de onde a transferência é iniciada. Sys_id do registro de fila ou o identificador de fila em um sistema externo. Se estiver usando um queue_id de um sistema externo, ele deverá ser mapeado para o campo ID da fila do provedor (external_id) no registro awa_queue. Este parâmetro é usado para criar um item de trabalho antes de iniciar a transferência se um item de trabalho ativo não for encontrado. Ele permite que as transferências sejam realizadas se a interação original tiver sido criada sem nenhum roteamento, como para chamadas de saída. Tipo de dados: cadeia de caracteres Tabela: fila [awa_queue] |
| transfer.target_id | Necessário para atribuições de transferência. Sys_id do agente ou registro de fila para o qual a atribuição será transferida.
Tipo de dados: cadeia de caracteres |
| transfer.target_type | Necessário para atribuições de transferência. Tipo de registro para o qual a atribuição será transferida. Valores válidos:
Tipo de dados: cadeia de caracteres |
| transfer.transfer_type | Necessário para atribuições de transferência. Tipo de transferência. Valores válidos:
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.
| 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 |
| 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.
| 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. Não foi possível processar a solicitação devido a um erro no item de trabalho do documento fornecido ou no sys_id do agente. |
| 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 |
|---|---|
| mensagem | Mensagem de resposta com informações sobre o sucesso ou a falha da atribuição. Valores possíveis:
|
| êxito | Sinalizador que indica se a atribuição foi bem-sucedida. Valores possíveis:
Tipo de dados: booliano |
| work_item | Detalhes sobre o item de trabalho criado ou atualizado. Tipo de dados: objeto |
| work_item.display_name | Nome de exibição do registro do documento. Tipo de dados: cadeia de caracteres |
| work_item.document_id | Sys_id do registro do documento. Tipo de dados: cadeia de caracteres |
| work_item.document_table | Nome da tabela associada ao documento. Tipo de dados: cadeia de caracteres |
| item_de_trabalho.fila | Sys_id do registro de fila ou o identificador de fila em um sistema externo. Tipo de dados: cadeia de caracteres Tabela: fila [awa_queue] |
| work_item.sys_id | Sys_id do item de trabalho. Tipo de dados: cadeia de caracteres Tabela: item de trabalho [awa_work_item] |
Solicitação de cURL
Este exemplo mostra como atribuir um item de trabalho a um agente.
curl "https://instance.servicenow.com/api/now/awa/documents/interaction/59616aba87bd5210be070d48dabb35e6/offer" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
"external_segment_id": "segment_59616aba87bd5210be070d48dabb35e6",
"queue_id": "92f8942787851210be070d48dabb35fb",
"assignment": {
"agent_sys_id": "0d584509c323120095ccd02422d3ae5b",
"allowed_to_decline": "true",
"enable_auto_assign": "false",
"timeout": 30,
"offered_on":"2024-04-03T23:09:31.000"
}
}'
--user 'username':'password'A resposta mostra que o item de trabalho foi atribuído com sucesso ao agente. Você pode verificar o resultado no campo Atribuído a do registro do item de trabalho [awa_work_item].
{
"result": {
"work_item": {
"display_name": "Interaction: IMS0000221",
"sys_id": "bfa3a27e87bd5210be070d48dabb3588",
"document_id": "59616aba87bd5210be070d48dabb35e6",
"document_table": "interaction",
"queue": "92f8942787851210be070d48dabb35fb"
},
"success": true,
"message": "Manual assignment successfully requested."
}
}