API de retorno de chamada Omichannel

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 42 min. de leitura

    • . Retorno de chamada omnichannel A API fornece métodos para criar, atualizar e iniciar uma solicitação de retorno de chamada para conversas do atendente.

    . Retorno de chamada omnicanal A API permite que os agentes chamem os usuários de forma programática em vez de esperar na fila por um agente disponível. Por exemplo, os agentes podem usar a funcionalidade de retorno de chamada para chamar os usuários de volta quando o tempo de espera do agente for longo ou quando não houver agentes disponíveis. Você pode executar as seguintes ações com esta API:
    • Crie uma nova solicitação de retorno de chamada imediata ou programe uma nova solicitação.
    • Crie uma interação inicial e interações de novas tentativas subsequentes.
    • Atualize um retorno de chamada existente.

    Esta API pertence ao namespace sn_omni_callback e requer a função Administrador com API de retorno de chamada [sn_omni_callback.callback_api].

    Para mais informações sobre Retorno de chamada omnicanal aplicação como um ServiceNow Capacidade da plataforma de IA, consulte Omnichannel Callback.

    Retorno de chamada omnichannel - POST api/sn_omni_callback/actions

    Fornece ações para integrar plataformas de contact center como serviço (CCaaS) de terceiros com ServiceNow® Omnichannel de Retorno de chamada sistema. Esta API atua como uma ponte, roteando operações de retorno de chamada (criar, atualizar, cancelar, fechar) para provedores de CCaaS externos por meio de configuração Workflow Studio subfluxos.

    Nota:
    Este endpoint funciona de forma semelhante a Retorno de chamada omnichannel - POST /api/sn_omni_callback/callback/create e. Retorno de chamada omnicanal - PATCH /api/sn_omni_callback/callback/update, mas é usado para atualizar ou criar retornos de chamada em uma integração de terceiros com contexto de roteamento.

    Roteamento inteligente

    . /ações o endpoint roteia de forma inteligente as solicitações de retorno de chamada com base em routingContextparâmetro. Quando uma regra de roteamento é configurada, a API usa uma estrutura de carga única e unificada para todas as ações e roteia a solicitação para um subfluxo de CCaaS usando Contexto de roteamento . Quando o roteamento é configurado, o conteúdo da solicitação nunca muda. Apenas o nível superior actiono valor é diferente.

    Nota:
    A API verifica regras de roteamento na tabela Configuração de roteamento de retorno de chamada [sys_cs_callback_routing_config] com base em routingContextparâmetro. Se uma regra correspondente for encontrada, a solicitação será encaminhada para o subfluxo personalizado configurado. O subfluxo pode se integrar a plataformas CCaaS externas ou implementar lógica de negócios personalizada. O subfluxo processa a solicitação e retorna a resposta.

    Se routingContextSe a regra de roteamento for omitida ou nenhuma correspondência de regra de roteamento, a API retornará para o padrão ServiceNow e espera o formato de carga padrão do correspondente PUBLICAR/criar , PATCH/atualização , ou PATCH /cancelar endpoints.

    Formato de URL

    URL com controle de versão: /api/sn_omni_callback/v1/actions

    URL padrão: /api/sn_omni_callback/actions

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Parâmetros do corpo da solicitação
    Nome Descrição
    Objeto Objeto que contém a operação e os detalhes.

    Tipo de dados: Objeto

    {
    "action": "String",
    "payload": {Object},
    "routingContext": {Object}
  }
    ação Necessário. Define a ação a ser executada no retorno de chamada.
    Valores aceitos:
    • criar : Cria um novo registro de retorno de chamada.
    • atualizar : Atualiza um registro de retorno de chamada existente com base no número de retorno de chamada.
    • fechar : Fecha um registro de retorno de chamada porque a solicitação de retorno de chamada foi atendida. Não inicia o retorno de chamada. Atualiza o campo Motivo na tabela Retorno de chamada [sys_cs_callback].
    • cancelar : Cancela um registro de retorno de chamada porque o cliente cancelou a solicitação e não precisa se conectar a um agente. Atualiza o campo Motivo na tabela Retorno de chamada [sys_cs_callback].

    Tipo de dados: Cadeia de caracteres
    carga Necessário. Objeto que contém dados específicos necessários para a ação fornecida quando routingContexto objeto foi aprovado. Para operações de fechamento e cancelamento, somente callbackIDé necessário na carga.
    Nota:
    Para criar e atualizar ações, se routingContextnão foi aprovado, use o. payloadestrutura do objeto documentada no Retorno de chamada omnichannel - POST /api/sn_omni_callback/callback/create e. Retorno de chamada omnicanal - PATCH /api/sn_omni_callback/callback/update, respectivamente. A seção "Exemplos" demonstra cenários de roteamento e não roteamento.

    Tipo de dados: Objeto

    payload estrutura para criar e atualizar ações.

    {
  "callbackContext": {Object},
  "callbackDetails": {Object},
  "callbackId": "String",
  "phoneNumber": "String",
  "type": "String"
}

    payload estrutura para fechar e cancelar ações.

    "payload": {
  "callbackId": "String"
}
    payload.callbackContext Opcional. Objeto que contém os detalhes de contexto sobre a solicitação de retorno de chamada.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context]

    Tipo de dados: Objeto

    "callbackContext": {
  "customer_timezone": "String",
  "ivr_path": "String",
  "queue": "String"
}
    payload.callbackContext.customer_timezone Fuso horário do cliente que solicitou o retorno de chamada. Os fusos horários podem ser fornecidos nos seguintes formatos.
    • País/Cidade : Por exemplo, América/Los_angeles .
    • País/fuso horário : Por exemplo, EUA/Pacífico .
    • Abreviação do fuso horário : Por exemplo, PST .

    Para obter uma lista completa de fusos horários válidos, consulte o campo Fuso horário na tabela Usuário [sys_user]. Para obter mais informações sobre fusos horários, consulte Time zones.

    Tipo de dados: Cadeia de caracteres
    payload.callbackContext.ivr_path O caminho de RVI (Resposta de voz interativa) que um cliente segue antes de ser transferido para um agente humano.

    Normalmente contém uma lista de filas ou opções de menu pelas quais o cliente navegou no sistema RVI. Esta cadeia de caracteres é passada pelo Contact Center as a Service (CCaaS). Por exemplo, "ivr_path": "Suporte técnico > Gestão de contas"

    Tipo de dados: Cadeia de caracteres
    payload.callbackContext.queue Atribuições numéricas na fila.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails Opcional. Objeto que contém os detalhes sobre a solicitação de retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Objeto

    "callbackDetails": {
  "description": "String",
  "end_time": "String",
  "expire_time": "String",
  "first_name": "String",
  "last_name": "String",
  "opened_by": "String",
  "phone_number": "String",
  "next_retry": "String",
  "reason": "String",
  "scheduled_start_time": "String",
  "short_description": "String",
  "state": "String", 
  "type": "String"
}
    payload.callbackDetails.description Explicação detalhada da solicitação de retorno de chamada. Pode incluir preocupações específicas do cliente, contexto ou anotações do agente.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.end_time A janela de tempo em que a solicitação de retorno de chamada deve ser concluída. Após esse carimbo de data/hora, o retorno de chamada será considerado atrasado ou expirado, a menos que seja reagendado. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.expire_time O tempo limite final após o qual a solicitação de retorno de chamada não deve mais ser tentada. Isso geralmente é usado para fechar ou cancelar automaticamente solicitações obsoletas.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.first_name Nome do cliente que está solicitando o retorno de chamada.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.last_name Sobrenome do cliente que está solicitando o retorno de chamada.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.opened_by Sys_id do usuário ou agente que criou ou iniciou a solicitação de retorno de chamada.

    Tabela: Usuário [sys_user]
    payload.callbackDetails.phone_number Número de telefone do cliente para retornar a chamada.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.next_retry O horário da próxima tentativa agendada se as tentativas de retorno de chamada anteriores não tiverem sido bem-sucedidas. Útil para lógica de nova tentativa automatizada ou manual.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.reason Motivo da solicitação de retorno de chamada. Ajuda com roteamento, análise e emissão de relatórios marcando o retorno de chamada com um motivo padronizado.
    Valores válidos:
    • Outro problema
    • Valores personalizados definidos pela sua implementação. Por exemplo, "Consulta de faturamento" , "Suporte técnico"

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Reason_type

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.scheduled_start_time Valor de data e hora em que a janela de retorno de chamada começa. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.short_description Um breve resumo da solicitação de retorno de chamada, geralmente usado em listas ou painéis.

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.state O status atual do fluxo de trabalho da solicitação de retorno de chamada.
    Valores válidos:
    • aprovação pendente
    • em andamento
    • concluído
    • cancelado(a)

    Tipo de dados: Cadeia de caracteres
    payload.callbackDetails.type A categoria da solicitação. O valor é sempre retorno de chamada .
    payload.callbackId Necessário. Sys_id ou external_id do retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    PhoneNumber.phoneNumber Necessário. Número de telefone do usuário que está solicitando o retorno de chamada.

    Tipo de dados: Cadeia de caracteres
    carga.type Necessário. Tipo de retorno de chamada.

    Valor válido: callback_request

    Tipo de dados: Cadeia de caracteres
    Contexto de roteamento Necessário para configuração de roteamento. Se não for aprovado ou se a regra de roteamento não corresponder, o endpoint de ações não invocará um subfluxo de CCaaS e retornará para usar o padrão ServiceNow processando.

    Informações contextuais usadas para encontrar um subfluxo personalizado ou regra de roteamento. Se omitida, a API usará o processamento de retorno de chamada padrão.

    Tipo de dados: Objeto

    "routingContext": {
 "sourceTable": "String",
 "sourceId": "String",
 "userId": "String"
}
    Context.sourceId Sys_id do registro de origem que inicia o retorno de chamada. Corresponde ao valor de sourceTable.

    Tipo de dados: Cadeia de caracteres
    Context.sourceTable O nome da tabela em que a solicitação se originou.
    Valores aceitos:
    • sp_portal
    • sn_csm_ec_engmnt_center_module
    • sn_incorporável_core_module

    Tipo de dados: Cadeia de caracteres
    routingContext.userId Usuário que inicia a solicitação (geralmente o agente ou o usuário do sistema).

    Tabela: Usuário [sys_user]

    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 da 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
    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 REST API códigos de resposta HTTP .

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.

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

    Nome Descrição
    corpo Objeto que contém informações de sucesso ou falha sobre a solicitação.

    Tipo de dados: Objeto

    {
  "status": 200,
  "body": {
    "message": "String",
    "number": "String"
 }
}
    mensagem.corpo Mensagem com breves detalhes sobre o sucesso ou falha da ação.

    Tipo de dados: Cadeia de caracteres
    número.corpo O número de referência do retorno de chamada. Por exemplo, "Cal0010012" .

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    status Código de status correspondente da solicitação.

    Tipo de dados: Cadeia de caracteres

    Criar exemplo (roteamento habilitado)

    Esta ação cria um novo registro de retorno de chamada com o contexto de roteamento configurado.

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "create",
  "routingContext": {
    "sourceTable": "sn_csm_ec_engmnt_center_module",
    "sourceId": "a1b2c3d4e5f6a7b8",
    "userId": "beth.anglin"
  },
  "payload": {
    "callbackId": "cb-98765",
    "callbackDetails": {
      "first_name": "Alice",
      "last_name": "Smith",
      "state": "Pending Approval",
      "reason": "Request updated by user",
      "end_time": "2025-12-17T23:00:00Z",
      "scheduled_start_time": "2025-12-17T22:00:00Z",
      "next_retry": "2025-12-18T10:00:00Z",
      "expiry_time": "2025-12-18T12:00:00Z",
      "phone_number": "+14155552671",
      "short_description": "Callback request for customer support",
      "description": "Customer requested a callback regarding their recent order.",
      "opened_by": "user_sys_id_12345",
      "type": "callback"
    },
    "type": "callback_request",
    "phoneNumber": "+14155552671",
    "callbackContext": {
      "queue": "Customer Support",
      "ivr_path": "support/ivr-path",
      "customer_timezone": "GMT-5"
    }
  },
  "additional_parameters": {}
}

    Criar (sem contexto de roteamento)

    O exemplo a seguir demonstra como criar um novo registro de retorno de chamada sem contexto de roteamento.
    Nota:
    Criar ações sem contexto de roteamento siga a estrutura de solicitação documentada em Retorno de chamada omnichannel - POST /api/sn_omni_callback/callback/create.
    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "create",
  "payload": {
  "type": "asap",
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  },
  "callbackContext": {
    "queue": "sample queue",
    "ivr_path": "sample ivr path"
  },
  "inboundId": "ServiceNowVoice",
  "isExternal": true,
  "phoneNumber": "+123454768",
  "externalCallbackId": "new-external-id",
  "interactionDetails": {
    "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z",
    "userId": "32423424",
    "callerPhoneNumber": "+14089178877"
  }
}

    Ação de atualização (roteamento habilitado)

    Esta ação de exemplo atualiza um registro de retorno de chamada existente com contexto de roteamento. . callbackNumbero valor identifica o registro a ser atualizado : 

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "update",
  "payload": {
    "callbackDetails": {
      "appointment": "68cc0a5a9314521060320dd548373cbd",
      "description": "Customer reported issue with order #12345",
      "short_description": "Order issue",
      "reason_type": "product_issue",
      "expire_time": "2025-09-01 17:00",
      "messaging_channel": "web_channel_sys_id",
      "channel_to_callback": "genesys_channel_sys_id",
      "scheduled_start_time": "2025-09-01 1:00",
      "end_time": "2025-09-01 17:00",
      "user_document": "abel.tuter",
      "user_table": "sys_user"
    },
    "callbackContext": {
      "queue": "5 value changed via api",
      "ivr_path": "5 some-ivr-path changed via api"
    },
    "inboundId": "AmazonConnect",
    "phoneNumber": "+14089178877",
    "callbackId": "a16ead53fff0621088c6ffffffffffce"
  }
}

    Atualizar (sem contexto de roteamento)

    . o exemplo a seguir demonstra como atualizar um registro de retorno de chamada sem contexto de roteamento:
    Nota:
    As ações de atualização sem contexto de roteamento seguem a estrutura de solicitação documentada em Retorno de chamada omnicanal - PATCH /api/sn_omni_callback/callback/update.
    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "update",
  "payload": {
    "callbackDetails": {
      "appointment": "68cc0a5a9314521060320dd548373cbd",
      "description": "Customer reported issue with order #12345",
      "short_description": "Order issue",
      "reason_type": "product_issue",
      "expire_time": "2025-09-01 17:00",
      "messaging_channel": "web_channel_sys_id",
      "channel_to_callback": "genesys_channel_sys_id",
      "scheduled_start_time": "2025-09-01 1:00",
      "end_time": "2025-09-01 17:00",
      "user_document": "abel.tuter",
      "user_table": "sys_user"
    },
    "callbackContext": {
      "queue": "5 value changed via api",
      "ivr_path": "5 some-ivr-path changed via api"
    },
    "inboundId": "AmazonConnect",
    "phoneNumber": "+14089178877",
    "callbackId": "a16ead53fff0621088c6ffffffffffce"
  }
}

    Cancelar ação

    Esta ação de exemplo cancela um determinado registro de retorno de chamada com contexto de roteamento e atualiza o campo de motivo na tabela Retorno de chamada [sys_cs_callback].

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
    "action": "cancel",
    "routingContext": {
        "sourceTable": "sn_csm_ec_engmnt_center_module",
        "sourceId": "a1b2c3d4e5f6a7b8",
        "userId": "beth.anglin"
    },
     "payload": {
        "callbackId": "CAL0001234"
    }
}

    Cancelar (sem contexto de roteamento)

    O exemplo a seguir demonstra como cancelar um registro de retorno de chamada sem contexto de roteamento:

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "cancel",
  "payload": {
    "callbackId": "cb-98765"
  }
}

    Ação de encerramento (roteamento habilitado)

    Este exemplo fecha um registro de retorno de chamada com contexto de roteamento e atualiza o campo de motivo na tabela Retorno de chamada [sys_cs_callback]:

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
    "action": "close",
    "routingContext": {
        "sourceTable": "sn_csm_ec_engmnt_center_module",
        "sourceId": "a1b2c3d4e5f6a7b8",
        "userId": "beth.anglin"
    },
    "payload": {
        "callbackId": "CAL0001234"
    }
}

    Fechar (sem contexto de roteamento)

    O exemplo a seguir demonstra como fechar um registro de retorno de chamada sem contexto de roteamento:

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "close",
  "payload": {
    "callbackId": "cb-98765"
  }
}

    Retorno de chamada omnicanal - POST /api/sn_omni_callback/callback/attempt

    Inicia uma interação para um retorno de chamada existente, incluindo tentativas de novas tentativas.

    Formato de URL

    URL padrão: /api/sn_omni_callback/callback/attempt

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    CallbackId Necessário. Sys_id ou external_id do retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    InteractionDetails Opcional. Detalhes sobre a interação. Destinado a "o mais rápido possível" (imediato) tipos de retorno de chamada para que os detalhes da interação sejam roteados diretamente para o agente sem aguardar.

    Todos os detalhes da interação são passados na carga do Recurso de interação de voz - POST /cs/voice-interactions.

    Tipo de dados: Objeto

    "interactionDetails": {
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "userId": "String"
}
    interactionDetails.callerPhoneNumber Número de telefone de retorno de chamada do chamador. Este é o número que o agente usa para entrar em contato com o solicitante caso a chamada caia.

    Tipo de dados: Cadeia de caracteres

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    InteractionDetails.clientSessionId Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica. Essas informações vinculam os registros entre os dois sistemas.

    Tipo de dados: Cadeia de caracteres

    Formato: Normalmente um UUID ou token de sessão exclusivo gerado pelo sistema externo

    Padrão: Nenhum
    interactionDetails.userId Sys_id do usuário para retornar chamada.

    Tabela: Usuário [sys_user]

    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 da REST API compatíveis .

    Tabela 10. 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
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json

    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 REST API códigos de resposta HTTP .

    Tabela 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    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
    erros Mensagem que contém detalhes sobre as falhas da criação do retorno de chamada, como IDs de solicitação obrigatórios ausentes.

    Tipo de dados: Matriz de cadeias de caracteres

    "errors": ["String", "String"]
    mensagens Mensagem que contém detalhes sobre o sucesso da criação do retorno de chamada.

    Tipo de dados: Matriz de cadeias de caracteres

    "messages": ["String", "String"]
    resultado Resultado da solicitação.

    Tipo de dados: Objeto

    "result": {
  "status": "String",
  "response": {Object},
  "errors": [Array],
  "messages": [Array]
}
    resposta.resultado Objeto que contém IDs de retorno de chamada e interação da solicitação de retorno de chamada.

    Tipo de dados: Objeto

    "response": {
  "callback_created": Boolean
  "callback_id": "String",
  "interaction_id": "String"
}
    result.response.interaction_id Sys_id da interação recém-criada.

    Tabela: Interação [interaction]

    Tipo de dados: Cadeia de caracteres
    status.resultado Status de sucesso ou falha da solicitação.
    Valores válidos:
    • êxito
    • falha

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir demonstra uma solicitação de tentativa POST com detalhes sobre a interação inicial e as interações de novas tentativas subsequentes.

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/attempt' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "callbackId": "<ID#>",
  "interactionDetails": {
    "clientSessionId": "<ID#>",
    "userId": "<ID#>",
    "callerPhoneNumber": "+112345678901"
  }
}

    Corpo da resposta quando um callback_id válido é fornecido e uma nova interação foi criada com sucesso para o retorno de chamada.

    {
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "<Interaction ID#>"
    }
  }
}

    Corpo da resposta quando um callback_id inválido foi fornecido na solicitação.

    {
  "result": {
    "status": "failure",
    "response": {
      "interactionId": null
    },
    "errors": [
      "Callback not found for callback ID: <ID#>"
    ]
  }
}

    Corpo da resposta quando a interação já existe para o retorno de chamada fornecido (a mensagem retorna detalhes sobre a interação existente):

    {
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "<Interaction ID#>"
    },
    "messages": [
      "Active Interaction <Interaction ID#> already exists for callback <ID#>"
    ]
  }
}

    Retorno de chamada omnichannel - POST /api/sn_omni_callback/callback/create

    Inicia uma nova solicitação de retorno de chamada imediata ou programada com base nos detalhes fornecidos no corpo da solicitação. Para retornos de chamada imediatos, esta API cria o retorno de chamada e a interação. Para retornos de chamada agendados, cria o retorno de chamada com um ID de compromisso.

    Formato de URL

    URL com controle de versão: /api/sn_omni_callback/v1/callback/create

    URL padrão: /api/sn_omni_callback/callback/create

    Parâmetros de solicitação compatíveis

    Tabela 13. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    Tabela 14. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 15. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    Context de chamada Objeto que contém os detalhes de contexto sobre a solicitação de retorno de chamada.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context]

    Tipo de dados: Objeto

    "callbackContext": {
  "customer_timezone": "String",
  "ivr_path": "String",
  "source_channel": "String",
  "queue": "String",
  "voicemail_duration": "String",
  "voicemail_recorded_at": "String",
  "voicemail_transcript": "String",
  "voicemail_url": "String"
}
    Context.customer_timezone Fuso horário do cliente que solicitou o retorno de chamada. Os fusos horários podem ser fornecidos nos seguintes formatos .
    • País/Cidade . Por exemplo, América/Los_angeles .
    • País/fuso horário . Por exemplo, EUA/Pacífico .
    • Abreviação do fuso horário . Por exemplo, PST .

    Para obter uma lista completa de fusos horários válidos, consulte a hora zona Campo na tabela Usuário [sys_user]. Para obter mais informações sobre fusos horários, consulte Time zones.

    Tipo de dados: Cadeia de caracteres
    CallbackContext.ivr_path O caminho de RVI (Resposta de voz interativa) que um cliente segue antes de ser transferido para um agente humano.

    Normalmente contém uma lista de filas ou opções de menu pelas quais o cliente navegou no sistema RVI. Esta cadeia de caracteres é passada pelo Contact Center as a Service (CCaaS). Por exemplo, "ivr_path": "Suporte técnico > Gestão de contas"

    Tipo de dados: Cadeia de caracteres
    CallbackContext.queue Atribuições numéricas na fila.

    Tipo de dados: Cadeia de caracteres
    Context.source_channel Origem do retorno de chamada. Por exemplo, RVI, Web ou VA.

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_duration Tamanho do correio de voz em horas, minutos ou segundos.

    Campo: Duração do correio de voz

    Tipo de dados: Número
    Context.voicemail_recorded_at Carimbo de data/hora em que o correio de voz foi gravado.

    Campo: Correio de voz gravado em

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_transcrition Texto transcrito do correio de voz.

    Campo: Transcrição do correio de voz

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_url Link relativo para o registro de retorno de chamada que contém o correio de voz.

    Campo: URL do correio de voz

    Tipo de dados: Cadeia de caracteres
    CallbackDetails Objeto que contém os detalhes sobre a solicitação de retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Objeto

    "callbackDetails": {
  "appointment": "String",
  "channel_to_callback": "String",
  "description": "String",
  "end_time": "String",
  "expire_time": "String",
  "messaging_channel": "String",
  "reason_type": "String"
  "scheduled_start_time": "String",
  "short_description": "String",
  "user_document": "String",
  "user_table": "String"
}
    CallbackDetails.compromisso Sys_id do compromisso. Aplicável somente a um Programado tipo de retorno de chamada.

    Tabela: Agendamento de compromisso [sn_apptmnt_booking_appointment_booking]

    Tipo de dados: Cadeia de caracteres
    callbackDetails.channel_to_callback Canal de envio de mensagens de destino para rotear o retorno de chamada.

    Tabela: Canal de envio de mensagens [sys_cs_channel], Campo: Sys_id

    Tipo de dados: Cadeia de caracteres
    callbackDetails.description Descrição completa descrevendo o motivo do retorno de chamada, se necessário.

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.end_time Valor de data e hora para interromper a tentativa de retorno de chamada. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.expire_time Data e hora para fechar a solicitação de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.messaging_channel Origem do retorno de chamada. Identifica a interface do cliente que iniciou a solicitação de retorno de chamada, como um cliente web, aplicativo para celular ou messenger incorporado.

    Tabela: Canal de envio de mensagens [sys_cs_channel], Campo: Sys_id

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.reason_type Motivo da solicitação de retorno de chamada. Ajuda com roteamento, análise e emissão de relatórios marcando o retorno de chamada com um motivo padronizado.
    Valores válidos:
    • Outro problema
    • Valores personalizados definidos pela sua implementação. Por exemplo, "Consulta de faturamento" , "Suporte técnico"

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Reason_type

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.scheduled_start_time Valor de data e hora para iniciar o retorno de chamada. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.short_description Fornece uma explicação detalhada da solicitação de retorno de chamada. Pode incluir preocupações específicas do cliente, contexto ou anotações do agente.

    Tipo de dados: Cadeia de caracteres
    callbackDetails.user_document Sys_id do usuário que solicitou o retorno de chamada. Usado com callbackDetails.user_tablepara identificar o usuário que está solicitando o retorno de chamada.

    Tabela: Usuário [sys_user], Campo: Sys_ id

    Tipo de dados: Cadeia de caracteres
    callbackDetails.user_table Tabela em que reside o registro do usuário. Usado com callbackDetails.user_documentpara identificar o usuário que está solicitando o retorno de chamada. O valor é sempre sys_user .

    Tipo de dados: Cadeia de caracteres
    ExternalCallbackId Identificador externo do retorno de chamada que foi criado em um fornecedor de terceiros.

    Tipo de dados: Cadeia de caracteres
    inboundId Sys_id da chamada de entrada associada ao retorno de chamada. Fornece rastreabilidade que vincula a solicitação de retorno de chamada a um registro de chamada de entrada específico que pode se originar de um provedor terceirizado ou plataforma de CCaaS.

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Provider_application_id

    Tipo de dados: Cadeia de caracteres
    InteractionDetails Opcional. Detalhes sobre a interação. Destinado a "o mais rápido possível" (imediato) tipos de retorno de chamada para que os detalhes da interação sejam roteados diretamente para o agente sem aguardar.

    Todos os detalhes da interação são passados na carga do Recurso de interação de voz - POST /cs/voice-interactions.

    Tipo de dados: Objeto

    "interactionDetails": {
  "callerPhoneNumber": "String",
  "clientSessionId": "String",
  "userId": "String"
}
    interactionDetails.callerPhoneNumber Número de telefone de retorno de chamada do chamador. Este é o número que o agente usa para entrar em contato com o solicitante caso a chamada caia.

    Tipo de dados: Cadeia de caracteres

    E.164 em conformidade com o padrão

    Padrão: Nenhum
    InteractionDetails.clientSessionId Identificador exclusivo de um registro em um sistema externo usado para rastrear esta chamada telefônica. Essas informações vinculam os registros entre os dois sistemas.

    Tipo de dados: Cadeia de caracteres

    Formato: Normalmente um UUID ou token de sessão exclusivo gerado pelo sistema externo

    Padrão: Nenhum
    interactionDetails.userId Sys_id do usuário para retornar chamada.

    Tabela: Usuário [sys_user]

    Tipo de dados: Cadeia de caracteres
    isExternal Sinalizador que indica se o retorno de chamada é externo e foi solicitado em um fornecedor de terceiros diferente.
    Valores válidos:
    • Retorno de chamada é externo.
    • Retorno de chamada não é externo.

    Padrão: falso
    tipo Obrigatório. Tipo de retorno de chamada.
    Valores válidos:
    • o mais rápido possível : A interação de retorno de chamada é criada instantaneamente.
    • programado : A interação de retorno de chamada é criada e programada para um horário posterior selecionado pelo cliente.

    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 da REST API compatíveis .

    Tabela 16. 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
    Tabela 17. Cabeçalhos de resposta
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json

    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 REST API códigos de resposta HTTP .

    Tabela 18. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    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
    resultado Resultado da solicitação.

    Tipo de dados: Objeto

    "result": {
  "status": "String",
  "response": {Object},
  "errors": [Array],
  "messages": [Array]
}
    resultado.erros Mensagem que contém detalhes sobre as falhas da criação do retorno de chamada, como IDs de solicitação obrigatórios ausentes.

    Tipo de dados: Matriz de cadeias de caracteres

    "errors": ["String", "String"]
    resultado.mensagens Mensagem que contém detalhes sobre o sucesso da criação do retorno de chamada.

    Tipo de dados: Matriz de cadeias de caracteres

    "messages": ["String", "String"]
    resposta.resultado Objeto que contém IDs de retorno de chamada e interação da solicitação de retorno de chamada.

    Tipo de dados: Objeto

    "response": {
  "callback_created": Boolean
  "callback_id": "String",
  "interaction_id": "String"
}
    result.response.callback_created

    Sinalizador que indica se a nova solicitação de retorno de chamada foi criada ou não.

    Valores possíveis:
    • Retorno de chamada criado com sucesso.
    • Retorno de chamada não criado. Por exemplo, o retorno de chamada já existe com o callback_id fornecido.

    Tipo de dados: Booliano
    result.response.callback_id Sys_id do novo retorno de chamada, se aplicável.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    result.response.interaction_id Sys_id da interação recém-criada.

    Tabela: Interação [interaction]

    Tipo de dados: Cadeia de caracteres
    status.resultado Status de sucesso ou falha da solicitação.
    Valores válidos:
    • êxito
    • falha

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir cria uma solicitação de retorno de chamada simples de acordo com os detalhes fornecidos pelo agente no corpo da solicitação.

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/create' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "type": "asap",
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  },
  "callbackContext": {
    "queue": "sample queue",
    "ivr_path": "sample ivr path"
  },
  "inboundId": "ServiceNowVoice",
  "isExternal": true,
  "phoneNumber": "+123454768",
  "externalCallbackId": "new-external-id",
  "interactionDetails": {
    "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z",
    "userId": "32423424",
    "callerPhoneNumber": "+14089178877"
  }
}

    O corpo da resposta retorna uma resposta de sucesso com IDs de retorno de chamada e interação para a solicitação de retorno de chamada recém-criada.

    {
  "status": "success",
  "response": {
    "callback_id": "a16ead53fff0621088c6ffffffffffce",
    "interaction_id": "696e6d57fff0621088c6ffffffffff7d"
  }
}

    Corpo da resposta quando os detalhes da interação não foram fornecidos:

    {
  "status": "success",
  "response": {
    "callback_created": true,
    "callback_id": "7df2059ffffc221088c6ffffffffff0c"
  }
}

    Corpo da resposta quando o ID de retorno de chamada já existe, mas novos detalhes da interação foram fornecidos:

    {
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "84054fff53786210011eddeeff7b12d6",
      "callback_id": "8b43c3fb53786210011eddeeff7b12a6",
      “callback_created”: false
    },
    "messages": [
      "Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6",
      "Successfully created the interaction 84054fff53786210011eddeeff7b12d6"
    ]
  }
}

    Corpo da resposta quando o ID de retorno de chamada já existe, mas os novos detalhes da interação não foram fornecidos:

    {
  "result": {
    "status": "success",
    "response": {
      "callback_id": "8b43c3fb53786210011eddeeff7b12a6"
    },
    "messages": [
      "Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6"
    ]
  }
}

    Corpo da resposta quando os campos obrigatórios estão ausentes na solicitação:

    {
  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Parameter 'type' is required in request"
    ]
  }
}

    Retorno de chamada omnichannel - POST api/ sn_omni_callback/callback/callback/get

    Busca informações de retorno de chamada com base nos parâmetros de consulta.

    Formato de URL

    URL com controle de versão: /api/sn_omni_callback/v1/callback/get

    URL padrão: /api/sn_omni_callback/callback/callback/get

    Parâmetros de solicitação compatíveis

    Tabela 19. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    Tabela 20. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 21. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Parâmetros de consulta Objeto que contém o par chave-valor dos parâmetros de consulta para filtrar os resultados.

    Tipo de dados: Objeto

    "queryParameters": {
  "number": "String",
  "state": "String",
  "opened_by": "String",
  "sys_id", "String",
  "callback_type": "String",
  "external_callback_id": "String",
  "callback_number": "String"
}
    Parâmetros de consulta. número O número de referência do retorno de chamada a ser pesquisado. Por exemplo, "Cal0010012" .

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    Parameters.state Número que representa o estado atual do retorno de chamada.
    Valores possíveis:
    • 1 : Aberto
    • 2 : Trabalho em andamento
    • 3 : Encerrado concluído
    • 4 : Encerrado abandonado
    • 7 : Cancelado

    Tipo de dados: Número
    Parâmetros.opened_by ID do usuário que está solicitando o retorno de chamada.

    Tabela: Usuário [sys_user]

    Tipo de dados: Cadeia de caracteres
    Parâmetros.sys_id Sys_id do registro de retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    queryParameters.callback_type Tipo de retorno de chamada.
    Valores válidos:
    • o mais rápido possível : A interação de retorno de chamada é criada instantaneamente.
    • programado : A interação de retorno de chamada é criada e programada para um horário posterior selecionado pelo cliente.

    Tipo de dados: Cadeia de caracteres
    QueryParameters.external_callback_id Identificador externo para o retorno de chamada criado em um sistema de terceiros.

    Tipo de dados: Cadeia de caracteres
    queryParameters.callback_number Número de telefone do chamador para retornar a chamada.

    Tipo de dados: Cadeia de caracteres
    ResponseParameters Opcional. Especifica quais campos retornar na resposta. Se omitido, o endpoint retornará campos padrão.

    Tipo de dados: Objeto

    "responseParameters": {
  "callback": [Array],
  "context": [Array]
}
    responseParameters.callback Opcional. Retorna campos do registro de retorno de chamada (por exemplo, número , phone_number ).

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Objeto

    "callback": [String, String]
    Valores válidos:
    • número : Número de referência exclusivo para esse retorno de chamada (por exemplo, "Cal0010012" ).
    • phone_number : Número de telefone do chamador.
    Context.responseParameters Opcional. Retorna informações contextuais do retorno de chamada, como fila, atribuição ou metadados relacionados na forma de pares chave:valor.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context]

    Tipo de dados: Matriz de cadeias de caracteres

    "callbackContext": {
  "customer_timezone": "String",
  "ivr_path": "String",
  "source_channel": "String",
  "queue": "String",
  "voicemail_duration": "String",
  "voicemail_recorded_at": "String",
  "voicemail_transcript": "String",
  "voicemail_url": "String"
}
    ResponseParameters.context.customer_timezone Fuso horário de . usuário que está solicitando o retorno de chamada.

    Cadeia de caracteres
    ResponseParameters.context.ivr_path O caminho de RVI (Resposta de voz interativa) que um cliente segue antes de ser transferido para um agente humano.

    Normalmente contém uma lista de filas ou opções de menu pelas quais o cliente navegou no sistema RVI. Esta cadeia de caracteres foi passada por Contato CCaaS (Center as a Service, centro como serviço). Por exemplo, "ivr_path": "Suporte técnico > Gestão de contas"

    Tipo de dados: Cadeia de caracteres
    ResponseParameters.context.source_channel Origem do retorno de chamada. Por exemplo, RVI, Web ou VA.

    Cadeia de caracteres
    ResponseParameters.context.queue Nome ou ID da fila à qual o retorno de chamada é atribuído.

    Cadeia de caracteres
    ResponseParameters.context.voicemail_duration Tamanho do correio de voz em horas, minutos ou segundos.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context], Campo: Duração do correio de voz

    Cadeia de caracteres
    Parameters.context.voicemail_recorded_at Carimbo de data/hora em que o correio de voz foi gravado.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context], Campo : Correio de voz gravado em

    Tipo de dados: Cadeia de caracteres
    ResponseParameters.context.voicemail_transcrition Texto transcrito do correio de voz.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context], Campo: Transcrição do correio de voz

    Tipo de dados: Cadeia de caracteres
    ResponseParameters.context.voicemail_url Link relativo para o registro de retorno de chamada que contém o correio de voz.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context], Campo: URL do correio de voz

    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 da REST API compatíveis .

    Tabela 22. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Nenhum(a)
    Tabela 23. 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 REST API códigos de resposta HTTP .

    Tabela 24. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.

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

    Nome Descrição
    resultado Objeto que contém o registro de retorno de chamada ou as informações de retorno de chamada que correspondem aos critérios de pesquisa especificados.

    Tipo de data: Objeto

    "result": {
  "response": {Object},
  "status": "String"
}
    resposta.resultado Informações de retorno de chamada.

    Tipo de dados: Objeto

    "response": {
 "callbacks": [Array],
 "count": "Number"
}
    result.response.callbacks Objeto que contém detalhes sobre o registro de retorno de chamada na forma de pares chave:valor.
    Nota:
    Exibe todos os campos padrão se responseParametersnão foi especificado na solicitação.

    Tipo de dados: Matriz de cadeias de caracteres

    "callbacks": [
  {
    "number": "String",
    "state": "String",
    "first_name": "Virtual",
    "last_name": "Agent",
    "user_table": "sys_user",
    "opened_by": "Virtual Agent",
    "assigned_to": ""
  }
]
    result.response.callbacks.assigned_to ID do agente atribuído à solicitação.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.context Informações contextuais do registro de retorno de chamada. Varia de acordo com a entrada da solicitação.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context]

    Tipo de dados: Matriz de cadeias de caracteres

    "callbackContext": {
  "customer_timezone": "String",
  "ivr_path": "String",
  "source_channel": "String",
  "queue": "String",
  "voicemail_duration": "String",
  "voicemail_recorded_at": "String",
  "voicemail_transcript": "String",
  "voicemail_url": "String"
}
    result.response.callbacks.context.customer_timezone Fuso horário do usuário que está solicitando o retorno de chamada.

    Cadeia de caracteres
    result.response.callbacks.context.ivr_path O caminho de RVI (Resposta de voz interativa) que um cliente segue antes de ser transferido para um agente humano.

    Normalmente contém uma lista de filas ou opções de menu pelas quais o cliente navegou no sistema RVI. Esta cadeia de caracteres é passada pelo Contact Center as a Service (CCaaS). Por exemplo, "ivr_path": "Suporte técnico > Gestão de contas"

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.context.source_channel Origem do retorno de chamada. Por exemplo, RVI, Web ou VA.

    Cadeia de caracteres
    result.response.callbacks.context.queue Nome ou ID da fila à qual o retorno de chamada é atribuído.

    Cadeia de caracteres
    result.response.callbacks.context.voicemail_duration Tamanho do correio de voz em horas, minutos ou segundos.

    Cadeia de caracteres
    result.response.callbacks.context.voicemail_recorded_at Carimbo de data/hora em que o correio de voz foi gravado.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.context.voicemail_transcript Texto transcrito do correio de voz.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.context.voicemail_url Link relativo para o registro de retorno de chamada que contém o correio de voz.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.created_on Carimbo de data/hora quando o retorno de chamada foi criado.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.first_name Nome do usuário que iniciou ou está associado ao retorno de chamada.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.last_name Sobrenome do usuário associado. Conclui o nome completo do usuário para registro em log, roteamento e exibição.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.number Número de referência de retorno de chamada exclusivo. Por exemplo, "Cal0010012" .

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.opened_by ID do usuário que está solicitando o retorno de chamada.

    Tabela: Usuário [sys_user]

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.phone_number Número de telefone do chamador.

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.status Status atual do retorno de chamada.
    Valores possíveis:
    • 1 : Aberto
    • 2 : Trabalho em andamento
    • 3 : Encerrado concluído
    • 4 : Encerrado abandonado
    • 7 : Cancelado

    Tipo de dados: Cadeia de caracteres
    result.response.callbacks.user_table Tabela a ser referenciada ao pesquisar detalhes do usuário de retorno de chamada. Por exemplo, sys_user.

    Tipo de dados: Cadeia de caracteres
    contagem.resposta.resultado Número de registros correspondentes de acordo com os critérios de pesquisa.

    Tipo de dados: Número
    status.resultado Status de sucesso ou erro da solicitação.
    Valores possíveis:
    • Erro: Falha interna ou inesperada, como falha de conexão do banco de dados, exceção do servidor ou erro de tempo de execução não detectado.
    • Falha: Não foi possível concluir a operação. Por exemplo: Nenhum registro encontrado, falha na validação ou parâmetro incompatível.
    • Not_found: A entidade consultada não existe.
    • Não autorizado: O chamador não tem permissões, credenciais ou acesso.
    • Invalid_request: Para parâmetros malformados, tipos incorretos ou campos obrigatórios ausentes.
    • Tempo limite: O sistema ascendente ou o banco de dados não retornou a tempo.
    • Partial_success: Alguns registros foram processados com sucesso ou alguns falharam.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo POST a seguir consulta registros de retorno de chamada especificamente abertos por um Virtual Agent ( "opened_by": "virtual.agent" ) e está em um estado fechado ( 4 ) E direciona a API para retornar somente o número de referência e o número de telefone do registro de retorno de chamada ( "callback": ["number", "callback_number"] ) em um contexto de fila ( "contexto": ["fila"] ).

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/get' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u 'username':'password' \ 
  -d {
  "queryParameters": {
    "opened_by": "virtual.agent",
    "state": 4,
  },
  "responseParameters": {
    "callback": ["number", "callback_number"],
    "context": ["queue"]
  }
}

    Corpo da resposta.

    {
  "result": {
    "status": "success",
    "response": {
      "callbacks": [
        {
          "number": "CAL0010036",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010037",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010001",
          "callback_number": "+918008509174",
          "context": {
            "queue": "queue"
          }
        },
        {
          "number": "CAL0010033",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010003",
          "callback_number": "+918008509174",
          "context": {
            "queue": "Soumya queue"
          }
        },
        {
          "number": "CAL0010035",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010038",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010034",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        }
      ],
      "count": 8
    }
  }
}
    O exemplo a seguir recupera informações de retorno de chamada com base em um ID externo correspondente, new-external-2325 . Porque a chamada não fornece responseParametersna solicitação, a resposta retorna o registro padrão completo.
    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/get' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u 'username':'password' \ 
  -d {
  "queryParameters": {
    "external_callback_id": "new-external-2325"
  }
}

    Corpo da resposta:

    {
  "result": {
    "status": "success",
    "response": {
      "callbacks": [
        {
          "number": "CAL0010038",
          "state": "Closed Abandoned",
          "first_name": "Virtual",
          "last_name": "Agent",
          "user_table": "sys_user",
          "opened_by": "Virtual Agent",
          "assigned_to": ""
        }
      ]
    }
  }
}

    Retorno de chamada omnicanal - PATCH /api/sn_omni_callback/callback/update

    Atualiza um retorno de chamada existente de acordo com os detalhes fornecidos na solicitação.

    Forneça parâmetros de solicitação somente no corpo da solicitação que você deseja atualizar.

    Formato de URL

    URL padrão: /api/sn_omni_callback/callback/callback/update

    Parâmetros de solicitação compatíveis

    Tabela 25. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    Tabela 26. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 27. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    Context de chamada Objeto que contém os detalhes de contexto sobre a solicitação de retorno de chamada.

    Tabela: Contexto de retorno de chamada [sys_cs_callback_context]

    Tipo de dados: Objeto

    "callbackContext": {
  "customer_timezone": "String",
  "ivr_path": "String",
  "source_channel": "String",
  "queue": "String",
  "voicemail_duration": "String",
  "voicemail_recorded_at": "String",
  "voicemail_transcript": "String",
  "voicemail_url": "String"
}
    Context.customer_timezone Fuso horário do cliente que solicitou o retorno de chamada. Os fusos horários podem ser fornecidos nos seguintes formatos .
    • País/Cidade . Por exemplo, América/Los_angeles .
    • País/fuso horário . Por exemplo, EUA/Pacífico .
    • Abreviação do fuso horário . Por exemplo, PST .

    Para obter uma lista completa de fusos horários válidos, consulte a hora zona Campo na tabela Usuário [sys_user]. Para obter mais informações sobre fusos horários, consulte Time zones.

    Tipo de dados: Cadeia de caracteres
    CallbackContext.ivr_path O caminho de RVI (Resposta de voz interativa) que um cliente segue antes de ser transferido para um agente humano.

    Normalmente contém uma lista de filas ou opções de menu pelas quais o cliente navegou no sistema RVI. Esta cadeia de caracteres é passada pelo Contact Center as a Service (CCaaS). Por exemplo, "ivr_path": "Suporte técnico > Gestão de contas"

    Tipo de dados: Cadeia de caracteres
    CallbackContext.queue Atribuições numéricas na fila.

    Tipo de dados: Cadeia de caracteres
    Context.source_channel Origem do retorno de chamada. Por exemplo, RVI, Web ou VA.

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_duration Tamanho do correio de voz em horas, minutos ou segundos.

    Campo: Duração do correio de voz

    Tipo de dados: Número
    Context.voicemail_recorded_at Carimbo de data/hora em que o correio de voz foi gravado.

    Campo: Correio de voz gravado em

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_transcrition Texto transcrito do correio de voz.

    Campo: Transcrição do correio de voz

    Tipo de dados: Cadeia de caracteres
    Context.voicemail_url Link relativo para o registro de retorno de chamada que contém o correio de voz.

    Campo: URL do correio de voz

    Tipo de dados: Cadeia de caracteres
    CallbackDetails Objeto que contém os detalhes sobre a solicitação de retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Objeto

    "callbackDetails": {
  "appointment": "String",
  "channel_to_callback": "String",
  "description": "String",
  "end_time": "String",
  "expire_time": "String",
  "messaging_channel": "String",
  "reason_type": "String"
  "scheduled_start_time": "String",
  "short_description": "String",
  "user_document": "String",
  "user_table": "String"
}
    CallbackDetails.compromisso Sys_id do compromisso. Aplicável somente a um Programado tipo de retorno de chamada.

    Tabela: Agendamento de compromisso [sn_apptmnt_booking_appointment_booking]

    Tipo de dados: Cadeia de caracteres
    callbackDetails.channel_to_callback Canal de envio de mensagens de destino para rotear o retorno de chamada.

    Tabela: Canal de envio de mensagens [sys_cs_channel], Campo: Sys_id

    Tipo de dados: Cadeia de caracteres
    callbackDetails.description Descrição completa descrevendo o motivo do retorno de chamada, se necessário.

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.end_time Valor de data e hora para interromper a tentativa de retorno de chamada. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.expire_time Data e hora para fechar a solicitação de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.messaging_channel Origem do retorno de chamada. Identifica a interface do cliente que iniciou a solicitação de retorno de chamada, como um cliente web, aplicativo para celular ou messenger incorporado.

    Tabela: Canal de envio de mensagens [sys_cs_channel], Campo: Sys_id

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.reason_type Motivo da solicitação de retorno de chamada. Ajuda com roteamento, análise e emissão de relatórios marcando o retorno de chamada com um motivo padronizado.
    Valores válidos:
    • Outro problema
    • Valores personalizados definidos pela sua implementação. Por exemplo, "Consulta de faturamento" , "Suporte técnico"

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Reason_type

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.scheduled_start_time Valor de data e hora para iniciar o retorno de chamada. Aplicável somente a um Programado tipo de retorno de chamada.

    Valor Glide_date_time, como aaaa-MM-dd HH:mm:ss

    Tipo de dados: Cadeia de caracteres
    CallbackDetails.short_description Fornece uma explicação detalhada da solicitação de retorno de chamada. Pode incluir preocupações específicas do cliente, contexto ou anotações do agente.

    Tipo de dados: Cadeia de caracteres
    callbackDetails.user_document Sys_id do usuário que solicitou o retorno de chamada. Usado com callbackDetails.user_tablepara identificar o usuário que está solicitando o retorno de chamada.

    Tabela: Usuário [sys_user], Campo: Sys_ id

    Tipo de dados: Cadeia de caracteres
    callbackDetails.user_table Tabela em que reside o registro do usuário. Usado com callbackDetails.user_documentpara identificar o usuário que está solicitando o retorno de chamada. O valor é sempre sys_user .

    Tipo de dados: Cadeia de caracteres
    CallbackId Necessário. Sys_id ou external_id do retorno de chamada.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    inboundId Sys_id da chamada de entrada associada ao retorno de chamada. Fornece rastreabilidade que vincula a solicitação de retorno de chamada a um registro de chamada de entrada específico que pode se originar de um provedor terceirizado ou plataforma de CCaaS.

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Provider_application_id

    Tipo de dados: Cadeia de caracteres
    phoneNumber Número de telefone do chamador.

    Tipo de dados: Cadeia de caracteres de números

    E.164 em conformidade com o padrão

    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 da REST API compatíveis .

    Tabela 28. 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
    Tabela 29. Cabeçalhos de resposta
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json

    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 REST API códigos de resposta HTTP .

    Tabela 30. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    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
    erros Mensagem que contém detalhes sobre as falhas da criação do retorno de chamada, como IDs de solicitação obrigatórios ausentes.

    Tipo de dados: Matriz de cadeias de caracteres

    "errors": ["String", "String"]
    mensagens Mensagem que contém detalhes sobre o sucesso da criação do retorno de chamada.

    Tipo de dados: Matriz de cadeias de caracteres

    "messages": ["String", "String"]
    resultado Resultado da solicitação.

    Tipo de dados: Objeto

    "result": {
  "status": "String",
  "response": {Object},
  "errors": [Array],
  "messages": [Array]
}
    resposta.resultado Objeto que contém IDs de retorno de chamada e interação da solicitação de retorno de chamada.

    Tipo de dados: Objeto

    "response": {
  "callback_created": Boolean
  "callback_id": "String",
  "interaction_id": "String"
}
    result.response.callback_created

    Sinalizador que indica se a nova solicitação de retorno de chamada foi criada ou não.

    Valores possíveis:
    • Retorno de chamada criado com sucesso.
    • Retorno de chamada não criado. Por exemplo, o retorno de chamada já existe com o callback_id fornecido.

    Tipo de dados: Booliano
    result.response.callback_id Sys_id do novo retorno de chamada, se aplicável.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    result.response.interaction_id Sys_id da interação recém-criada.

    Tabela: Interação [interaction]

    Tipo de dados: Cadeia de caracteres
    status.resultado Status de sucesso ou falha da solicitação.
    Valores válidos:
    • êxito
    • falha

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir atualiza alguns detalhes de retorno de chamada na solicitação de retorno de chamada associada.

    curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/update' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  "callbackContext": {
    "queue": "5 value changed via api",
    "ivr_path": "5 some-ivr-path changed via api"
  },
  "inboundId": "AmazonConnect",
  "phoneNumber": "+14089178877",
  "callbackId": "a16ead53fff0621088c6ffffffffffce"
}
    Resposta de uma atualização bem-sucedida do ID de retorno de chamada válido existente.
    {
  "result": {
    "status": "success",
    "response": {
      "callback_id": "952f763b53786210011eddeeff7b1297"
    },
    "messages": [
      "Successfully updated the callback 952f763b53786210011eddeeff7b1297"
    ]
  }
}
    Resposta quando um ID de retorno de chamada inválido é fornecido na solicitação:
    
  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Callback not found for callback ID: 952f763b53786210011eddeef7b1297"
    ]
  }
}
    Resposta quando um ID de retorno de chamada está ausente na solicitação:
    
  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Parameter 'callbackId' is required in request"
    ]
  }
}

    Retorno de chamada omnichannel - PATCH /api/sn_omni_callback/callback/ fechar /( callback_number)

    Cancela uma determinada solicitação de retorno de chamada.

    Formato de URL

    URL com controle de versão: /api//sn_omni_callback/callback/close/

    URL padrão: /api/sn_omni_callback/callback/close/

    Parâmetros de solicitação compatíveis

    Tabela 31. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. 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
    callback_number SYS_id ou external_id do retorno de chamada a ser cancelado.

    Tabela: Retorno de chamada [sys_cs_callback]

    Tipo de dados: Cadeia de caracteres
    Tabela 32. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 33. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    motivo Opcional. Especifica o cancelamento o retorno de chamada fornecido. O valor é sempre Cancelado . Se reasonnão foi aprovado, a solicitação é encerrada em vez de cancelada.

    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 da REST API compatíveis .

    Tabela 34. 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
    Tabela 35. 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 REST API códigos de resposta HTTP .

    Tabela 36. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.

    Parâmetros do corpo da resposta

    Nome Descrição
    motivo Motivo para atualizar a solicitação de retorno de chamada. O valor é sempre Cancelado ou Encerrado .

    Tabela: Retorno de chamada [sys_cs_callback], Campo: Motivo

    Tipo de dados: Cadeia de caracteres

    {
"reason": "Cancelled"
}

    Solicitação de curl

    A solicitação a seguir cancela a solicitação de retorno de chamada com o ID de retorno de chamada CAL0001234.

    curl -X POST "https://instance.servicenow.com/api/sn_omni_callback/callback/close/CAL0001234" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "reason": "Cancelled"
  }'

    O corpo da resposta confirma o cancelamento.

    {
"reason":"Cancelled"
}