Skip to main content

API

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://api-docs.omni.code7.cloud/7#/. Após isso, é só clicar no botão Authenticate 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

O próximo passo é realizar o login na API, para isso, é necessário clicar no campo /Login/loginApi e depois no botão “Try it out”:

Acessar LoginAPI

A API em questão, está esperando duas variáveis o login e a senha. 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

Neste caso, vamos precisar copiar o id da organização 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 APIs 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: