Skip to main content

API - Dados Históricos

Como fazer uso das APIs do Omni

Este documento vai mostrar de forma prática e explicativa como fazer o uso das APis do Omni, que estão disponíveis no link a seguir: https://docs-history.omni.digitalcontact.cloud/.

Autenticação​

Para fazer uso da API do Omni, é preciso primeiramente realizar a autenticação. Para isso, é preciso copiar o x-api-key que está localizado no menu de canais dentro do Omni. Após isso, é só clicar no botão “Copiar API Key”, como mostra o print a seguir:

Copiar x_api_key

Com a key copiada, é preciso acessar as APIs do Omni por este link: https://docs-history.omni.digitalcontact.cloud/. Após isso, é só clicar no botão Authorize e colar a key no campo api_key. Segue os prints com o passo a passo abaixo:

Colar x_api_key 1

Colar x_api_key 2

APIs de Login

Atualmente, existem duas APIs de login, a /Login/loginApi que vamos ver é necessária para executar as requisições do módulo de contato ou integração e a /Login/organization serve para executar as requições de relatório (reports).

Login - Contato ou Integração

A API em questão, está esperando duas variáveis o login e a senha. Para executar a API, é necessário clicar no campo /Login/loginApi e depois no botão “Try it out”:

Acessar LoginAPI

Após inserir estes dados, é só clicar em execute, então a API vai retornar os dados das organizações que seu usuário está associado. Como mostra o exemplo a seguir:

Exemplo de retorno LoginAPI

Se o intuito é executar as APIs de contato ou integração, é só copíar o token no campo “Authorization” e adicionar Bearer e um espaço antes do token. após isso é necessário clicar no botão Authorize, como mostra o print a seguir:

Authorization

Pronto, agora será possível usar todas as APIs de contato/integração que estão disponíveis.

Login - Relatórios

Para executar as APIs de report, vamos precisar copiar o id da organização da API /Login/loginApi e depois selecionar a API /Login/organization e clicar novamente no botão “Try it out”:

Acessar LoginOrg

Essa API está esperando o login, senha e a organization id que foi copiado anteriormente. Após colocar estes dados, é só clicar em execute e a API retornará o token e os dados da organização. Como mostrar o exemplo abaixo:

Exemplo de retorno LoginOrg

Neste caso, vamos precisar só do token. Após copiar o token, podemos voltar para o menu “Authorize”, onde colocamos a api_key. Agora é só copíar o token no campo “Authorization” e adicionar Bearer e um espaço antes do token. após isso é necessário clicar no botão Authorize, como mostra o print a seguir:

Authorization

Pronto, agora será possível usar todas as APIs de relatório que estão disponíveis. Além disso, segue um vídeo demonstrando todos os passos citados anteriormente:

As principais rotas, são as seguintes:

  • service-history:
    • Vai capturar os dados de todos os atendimentos entre datas específicadas na requisição.
  • voice-log
    • Retornará os dados das chamadas receptivas e ativas, entre datas específicadas na requisição.
  • service-history-audio-links
    • Rota na qual é possível obter o link das gravações dos atendimentos realizados na plataforma, entre datas específicadas na requisição.

Service-history

A rota service-history está esperando três variáveis, segue a explicação:

  • report-skip
    • Define qual a página de documentos a API vai retornar, por padrão, o valor é 0. A API vai retornar 1000 documentos por página, sendo necessário aumentar este valor para capturar os outros atendimentos.
  • date_ini
    • De maneira geral, é a data inicial que a API vai levar em conta quando procurar os atendimentos. A rota aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 00:00:00.
  • date_end
    • Em geral, é a data final que a API vai levar em conta quando procurar os atendimentos. Assim como a date_ini, a date_end aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 23:59:00.

Após realizada a requisição, a API irá retornar um conjunto de informações de cada atendimento. Segue a definição de cada atributo retornado:

  • Total
    • A quantidade total de documentos encontrados.
  • Página
    • Valor informado no campo “report_skip” ao gerar os dados para criar o response.
  • Data
    • Consta a listagem de toda informação encontrada dentro dos parâmetros previamente informados.
    • agente
      • Nome do usuário/agente que recebeu o atendimento;
    • agent
      • E-mail do usuário/agente;
    • cliente
      • Identificador do cliente (número de telefone, email, id boteria, etc);
    • contato
      • Nome do contato;
    • data_inicio
      • Data e hora que foi recebido o atendimento. Para midia chat é a hora de entrada no Omni;
    • data_atendida
      • Data de início do atendimento entre cliente e agente. Para midia chat é a data/hora da primeira interação do agente;
    • data_fim
      • Data de encerramento do atendimento;
    • data_primeira_resposta
      • Data da primeira resposta do agente;
    • midia
      • Código da mídia em que foi realizado o atendimento;
    • portfolio
      • Informação se o atendimento é carteirizado ou não;
    • protocolo
      • Identificador único do atendimento;
    • ramal
      • Ramal do Agente;
    • serviço
      • Nome do Serviço utilizado para o atendimento;
    • documento_cliente
      • CPF ou CNPJ do contato;
    • status
      • Status da chamada;
    • tag
      • Nome da tag ou tabulação utilizada para finalizar o atendimento;
    • recebida
      • Fluxo da interação;
    • comentarios_internos
      • Comentários internos do atendimento;
    • id
      • Chave utilizada internamente.

Para acessar essa rota, é só ir no campo /ReportsApi/service-history e clicar no botão “Try it out”:

Acessar rota de service-history

Após de colocar os dados, é só clicar no botão execute que está logo abaixo do painel:

Executar a requisição service-history

Segue um exemplo de retorno da API service-history:

Exemplo de retorno service-history

Voice-log

Assim como a rota de service-history, a rota de voice-log está esperando três variáveis, segue a explicação:

  • report-skip
    • Define qual a página de documentos a API vai retornar, por padrão, o valor é 0. A API vai retornar 1000 documentos por página, sendo necessário aumentar este valor para capturar as outras chamadas.
  • date_ini
    • Em regra, é a data inicial que a API vai levar em conta quando procurar as chamadas. A rota aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 00:00:00.
  • date_end
    • De maneira geral, é a data final que a API vai levar em conta quando procurar as chamadas. Assim como a date_ini, a date_end aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 23:59:00.

Após realizada a requisição, a API irá retornar um conjunto de informações de cada chamada realizada. Segue a definição de cada atributo retornado:

  • Total
    • A quantidade total de documentos encontrados.
  • Página
    • Valor informado no campo “report_skip” ao gerar os dados para criar o response.
  • Data
    • Consta a listagem de toda informação encontrada dentro dos parâmetros previamente informados.
    • data_inicio
      • Data e hora que foi recebido o atendimento
    • data_atendida
      • Data de início do atendimento entre cliente e agente
    • data_primeira_resposta
      • Data da primeira resposta do agente
    • data_fim
      • Data de encerramento do atendimento
    • serviço
      • Nome do Serviço utilizado para o atendimento
    • agente
      • Nome do usuário/agente que recebeu o atendimento
    • agent
      • E-mail do usuário/agente;
    • ramal
      • Ramal do Agente
    • contato
      • Nome do contato
    • status
      • Status da chamada
    • portfolio
      • Informação se o atendimento é carteirizado ou não
    • tipo
      • Classificação pelo tipo da chamada, se de entrada ou saída
    • integração
      • Tipo de Integração
    • src_voice_log
      • Origem
    • from_voice_log
      • Identificador da origem
    • type_voice_log
      • Tipo de chamada, inbound ou outbound
    • voice_internal_status
      • Status interno da chamada
    • ipbx_external_endpoint
      • Endpoint externo
    • ipbx_dialed_string
      • Valor discado
    • ipbx_external_callerid
      • Id externo
    • ipbx_external_channel_id
      • Id canal externo
    • ipbx_external_channel_desc
      • Descrição do id canal externo
    • ipbx_external_channel_creationtime
      • Criação canal externo
    • ipbx_internal_channel_creationtime
      • Criação canal interno
    • service_flow_type_did
      • Fluxo did
    • ipbx_internal_channel_desc
      • Descrição do id canal interno
    • ipbx_internal_channel_id
      • Id canal interno
    • feature_request_type
      • Tipo request
    • transfer_result
      • Resultado da transferência
    • protocolo
      • Identificador único do atendimento
    • comentarios_internos
      • Comentários internos do atendimento
    • respostas_pesquisas
      • questão
        • Título da questão respondida
      • score
        • Score da resposta
      • status
        • Status da resposta
      • data encerramento
        • Data de finalização da resposta
      • id
        • Chave primaria da resposta
    • id
      • Chave primaria

Para acessar essa rota, é só ir no campo /ReportsApi/voice-log e clicar no botão “Try it out”:

Acessar rota de voice-log

Após de colocar os dados, é só clicar no botão execute que está logo abaixo do painel:

Executar a requisição voice-log

Segue um exemplo de retorno da API voice-log:

Exemplo de retorno voice-log

Service-history-audio-links

Assim como a rota de service-history e o voice-log, a rota de service-history-audio-links está esperando três variáveis, segue a explicação:

  • report-skip
    • Define qual a página de documentos a API vai retornar, por padrão, o valor é 0. A API vai retornar 1000 documentos por página, sendo necessário aumentar este valor para capturar as outros atendimentos.
  • date_ini
    • Em regra, é a data inicial que a API vai levar em conta quando procurar os atendimentos. A rota aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 00:00:00.
  • date_end
    • De maneira geral, é a data final que a API vai levar em conta quando procurar os atendimentos. Assim como a date_ini, a date_end aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 23:59:00.

Após realizada a requisição, a API irá retornar um conjunto de informações de cada atendimento. Segue a definição de cada atributo retornado:

  • Total
    • A quantidade total de documentos encontrados.
  • Página
    • Valor informado no campo “report_skip” ao gerar os dados para criar o response.
  • Data
    • Consta a listagem de toda informação encontrada dentro dos parâmetros previamente informados.
    • _id
      • Identificação da interação
    • data_inicio
      • Data e hora em que foi recebido o atendimento
    • data_atendida
      • Data e hora em que foi iniciado o atendimento
    • data_fim
      • Data e hora em que foi encerrado o atendimento
    • cliente
      • Identificador do Cliente
    • contato
      • Contato
    • agente
      • Nome do Agente
    • agent
      • E-mail do usuário/agente;
    • servico
      • Serviço
    • ramal
      • Ramal
    • origem
      • Inbound/Outbound
    • protocolo
      • Protocolo do atendimento
    • status
      • Status da chamada
    • documento
      • CPF ou CNPJ do contato
    • tag
      • Nome da tag ou tabulação utilizada para finalizar o atendimento
    • download_url
      • Link para arquivo (apenas para status Contact - chamada atendida)
    • id
      • Chave primaria

Para acessar essa rota, é só ir no campo /ReportsApi/service-history-audio-links e clicar no botão “Try it out”:

Acessar rota de service-history-audio-links

Após de colocar os dados, é só clicar no botão execute que está logo abaixo do painel:

Executar a requisição service-history-audio-links

Segue um exemplo de retorno da API service-history-audio-links:

Exemplo de retorno service-history-audio-links

Além disso, segue abaixo um vídeo explicando como executar as rotas vistas anteriormente:

Relatório de logins e pausas: activity-history​

Assim como as demais rotas de relatórios (reports) a rota de activty-history está esperando três variáveis, segue a explicação:

  • report-skip
    • Define qual a página de documentos a API vai retornar, por padrão, o valor é 0. A API vai retornar 1000 documentos por página, sendo necessário aumentar este valor para capturar os logins/logouts dos usuários.
  • date_ini
    • Em regra, é a data inicial que a API vai levar em conta quando procurar os logins/logouts dos usuários. A rota aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 00:00:00.
  • date_end
    • De maneira geral, é a data final que a API vai levar em conta quando procurar os logins/logouts dos usuários. Assim como a date_ini, a date_end aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 23:59:00.

Após realizada a requisição, a API irá retornar um conjunto de informações de cada login e pausa. Segue a definição de cada atributo retornado:

  • Total
    • A quantidade total de documentos encontrados.
  • Página
    • Valor informado no campo “report_skip” ao gerar os dados para criar o response.
  • Data
    • Consta a listagem de toda informação encontrada dentro dos parâmetros previamente informados.
    • agent_id:
      • ID do agente, para uso interno.
    • agente
      • Nome do usuário
    • agent
      • E-mail do usuário
    • evento
      • Tipo de ação que foi tomada – Login ou Pausa.
    • data_inicio
      • Data e hora de início do evento
    • data_fim
      • Data e hora do término do evento
    • id
      • Identificador para uso interno

Se houver pausas personalizadas configuradas no OMNI, o nome da pausa será retornado no campo evento, desde que algum usuário tenha registrado essa pausa. Para acessar essa rota, é só ir no campo /ReportsApi/activity-history e clicar no botão “Try it out”:

Acessar rota de activity-history

Após de colocar os dados, é só clicar no botão execute que está logo abaixo do painel:

Executar a requisição activity-history

Segue um exemplo de retorno da API activity-history:

Exemplo de retorno activity-history

Segue abaixo, um vídeo explicando como executar a rota de activity-history:

Relatório das pesquisas de satisfação: safistaction-survey-history​

Essa requisição retorna todas as pesquisas atribuidas aos atendimentos, dentro da data especificada. Assim como as demais rotas de relatórios (reports) a rota de satisfaction-survey está esperando três variáveis, segue a explicação:

  • report-skip
    • Define qual a página de documentos a API vai retornar, por padrão, o valor é 0. A API vai retornar 1000 documentos por página, sendo necessário aumentar este valor para capturar as pesquisas restantes.
  • date_ini
    • Em regra, é a data inicial que a API vai levar em conta quando procurar as pesquisas de satisfação. A rota aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 00:00:00.
  • date_end
    • De maneira geral, é a data final que a API vai levar em conta quando procurar as pesquisas de satisfação. Assim como a date_ini, a date_end aceita dois formatos de datas, com e sem o horário definido. Segue as duas formas como exemplo: 2024-12-31, 2024-12-31 23:59:00.

Após realizada a requisição, a API irá retornar um conjunto de informações de cada pesquisa de satisfação. Segue a definição de cada atributo retornado:

  • Total
    • A quantidade total de documentos encontrados.
  • Página
    • Valor informado no campo “report_skip” ao gerar os dados para criar o response.
  • Data
    • Consta a listagem de toda informação encontrada dentro dos parâmetros previamente informados.
    • data_inicio:
      • Data e hora em que foi recebida a resposta da pesquisa
    • data_fim
      • Data e hora em que foi encerrada a resposta da pesquisa
    • data_completado
      • Data e hora em que foi completada a resposta da pesquisa
    • media_type
      • Tipo de mídia, 1 - Voz, 2 - Chat e 4 - Whatsapp
    • voice_type
      • Para chamadas de voz, inbound ou outbound
    • research_type
      • CSAT ou NPS
    • question_id
      • Identificador da questão para uso interno
    • score
      • Nota da pesquisa
    • completed
      • Se completou a pesquisa, sim ou não
    • satisfaction_nps_level
      • Nível NPS
    • calculation_type
      • Tipo de cálculo
    • satisfaction_level
      • Nível de satisfação
    • status
      • Status da resposta
    • protocolo
      • Protocolo do atendimento
    • questão
      • Título da questão respondida
    • agente
      • Nome do Agente
    • agent
      • E-mail do agente
    • contato
      • Nome/Código/identificador do contato
    • id
      • Chave única para uso interno.

Para acessar essa rota, é só ir no campo /ReportsApi/satisfaction-survey-history e clicar no botão “Try it out”:

Acessar rota de satisfaction-survey-history

Após de colocar os dados, é só clicar no botão execute que está logo abaixo do painel:

Executar a requisição satisfaction-survey-history

Segue um exemplo de retorno da API satisfaction-survey-history:

Exemplo de retorno satisfaction-survey-history

Segue abaixo, um vídeo explicando como executar a rota de satisfaction-survey-history: