API openframe

Referência de API do Yokohama

Release

yokohama

ft:locale

pt-BR

ft:publication_title

Referência de API do Yokohama

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

API openframe

Versão de lançamento: Yokohama

Atualizado 30 de jan. de 2025

8 min. de leitura

A API openframe fornece endpoints que fornecem ao Centro de contato como serviço (CCaaS) a capacidade de criar e atualizar registros de interação sem usar o Manipulador de operações.

Use esta API para criar registros de interação para rastrear chamadas telefônicas do agente. Depois que um registro de interação é criado, a interação pode ser exibida automaticamente no Espaço configurável do CSM quando um agente recebe uma chamada telefônica.

Para acessar esta API, o plug-in com.sn_openframe_store deve ser instalado na instância e o usuário de chamada deve ter a função sn_openframe_api_user ou sn_openframe_user. A API openframe é executada no namespace sn_openframe.

Para obter informações adicionais sobre registros de interação de voz do CSM, consulte CSM voice interaction record page.

openframe – PATCH /openframe/voice-interaction/{interactionSysId}

Atualiza o registro de interação especificado na tabela Interação [interação]. Os provedores de Central de contato como serviço (CCaaS) podem usar esses registros para rastrear chamadas telefônicas.

Formato da URL

URL com controle de versão: /api/now/openframe/{api_version}/voice-interaction/{interactionSysId}

URL padrão: /api/now/openframe/voice-interaction/{interactionSysId}

Nota:

As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 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
interactionSysId	Sys_id do registro de interação a ser atualizado. Este valor é retornado pelo endpoint Criar interação de voz/POST. Tipo de dados: cadeia de caracteres Tabela: interação [interação]

Tabela 2. Parâmetros de consulta
Nome	Descrição
Nenhum(a)

Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
Nome	Descrição
interação	Obrigatório. Detalhes da interação de voz. Pelo menos um parâmetro deve ser passado. Tipo de dados: objeto `"interaction": { "additionalParams": {Object}, "callbackPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userPhoneNumber": "String" }`
interaction.additionalParams	Pares de nome-valor dos campos de registro de interação associados e seus respectivos valores. Por exemplo: `"additionalParams": { "direction": "inbound", "short_description": "New outbound call", "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a" }` Tipo de dados: objeto Padrão: nenhum
interaction.callbackPhoneNumber	Número de telefone de retorno de chamada do solicitante. Este é o número que o agente usa para entrar em contato com o chamador, caso a chamada caia. Tipo de dados: cadeia de caracteres Formato: E.164 Padrão: nenhum
Interação.clientSessionId	Identificador exclusivo do 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 Padrão: nenhum
Interação.InboundId	Identificador exclusivo do provedor de aplicações para o serviço de voz. Tabela: campo de ID de entrada na tabela Aplicação de canal do provedor [sys_cs_provider_application]. Padrão: nenhum
interação.userPhoneNumber	Número de telefone do usuário que fez a chamada associada à interação de voz. Tipo de dados: cadeia de caracteres Formato: E.164
interaçãoContexto	Variáveis de contexto de interação a serem definidas. Pares de nome-valor das variáveis de contexto de interação a serem salvos no registro de interação. Esses valores são determinados pelo CCaaS. Por exemplo: `"interactionContext":{ "devicetype": "genesys", "requester_session_language": "en-US" }` Tipo de dados: objeto Padrão: nenhum
logs de telefone	Pares de nome-valor dos logs de telefone a serem criados e associados a uma chamada. Você pode especificar qualquer campo na tabela Log de telefone [sn_open_frame_phone_log]. Por exemplo: `"phoneLogs":[ { "agent": "String", "call_id": "String", "start_time": "String" } ]` Tipo de dados: matriz de objetos Padrão: nenhum
registros relacionados	Registros relacionados à chamada. Tipo de dados: matriz de objetos `"relatedRecords":[ { "documentId": "String", "documentTable": "String" } ]` Padrão: nenhum
relatedRecords.documentId	Sys_id do registro relacionado. Tipo de dados: cadeia de caracteres Tabela: especificada no parâmetro relatedRecords.documentTable.
relatedRecords.documentTable	Nome da tabela que contém o registro relacionado. Tipo de dados: cadeia de caracteres

Cabeçalhos

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

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

Tabela 5. Cabeçalhos de resposta
Cabeçalho	Descrição
Nenhum(a)

Códigos de status

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

Tabela 6. Códigos de status
Código do status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
400	Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
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
status	Status da atualização do registro. Valores possíveis: SUCESSO: o registro de interação foi atualizado com sucesso. FALHA: o registro de interação não foi atualizado.

Solicitação de cURL

O exemplo de código a seguir mostra como atualizar o registro de interação com o sys_id 12961fff7fb2d2102d0cd3cf8c86652b.

curl "http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New Poonam outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'pasword'

Resposta:

{
  "result": {
    "status": "SUCCESS"
  }
}

openframe – POST /openframe/voice-interaction

Cria um registro de interação na tabela Interação [interação] quando um agente aceita uma chamada. Os provedores de Central de contato como serviço (CCaaS) podem usar esses registros para rastrear chamadas telefônicas.

Use este endpoint para fornecer uma experiência consistente para os agentes, semelhante a outros canais nativos, como bate-papo e caso, ao aceitar chamadas telefônicas.