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://api-docs.omni.code7.cloud/7#/.

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:

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:

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”:

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:

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”:

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:

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:

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:

Principais rotas: service-history, voice-log e service-history-audio-links

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”:

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

Segue um exemplo de retorno da API 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”:

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

Segue um exemplo de retorno da API 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”:

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

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

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

---