|
|
Dígitro Neo Interact CTI Computer Telephony Integration |
A API Neo Interact CTI foi baseada na API da solução Dígitro Interact CTI, adaptada à arquitetura de Contact Center operada em nuvem (cloud computing). Ela permite a integração do Contact Center do Neo Interact com os sistemas legados dos clientes deste serviço, através de uma API para controle e operação de funcionalidades, combinada com a notificação de eventos. Através desta API é possível realizar o acompanhamento e controle de chamadas, recebimento de notificação de eventos e configurações do sistema. Esta API foi projetada para ser operada tanto a partir de servidores em back-end, como em aplicações desenvolvida para navegadores (browsers).
ATENÇÃO: Apesar desta API ser baseada na API da solução Dígitro Interact CTI, ela não é compatível com esta última, até porque o Neo Interact CTI sendo uma evolução deste serviço, traz consigo novos elementos e contextos de operação. A API do Neo Interact CTI contudo, procurou preservar o máximo de similaridades e conceitos da solução Dígitro Interact CTI, além de simplificar implementações e conceitos.
Podemos entender a API CTI do Neo Interact separando-a em dois elementos principais:
Comandos ao Neo Interact
Notificação de eventos
Assim como o Interact CTI a API de comandos do Neo Interact CTI foi baseada no modelo REST (Representation State Transfer) sobre o protocolo HTTPS.
O modelo REST pode ser considerado um conjunto de princípios e recomendações para interoperabilidade de serviços em rede, que agrega uma série de vantagens derivados da universalidade de seus conceitos já plenamente estabelecidos na internet. Sua simplicidade de uso, compreensibilidade, segurança, padronização, suporte em diferentes dispostivos e aplicações, operacionalidade em redes protegidas o tornal ideal para este fim.
Soluções totalmente aderentes aos princípios REST são comumente chamadas de RESTFul. Uma das recomendações da abordagem REST é a utilização de diversos métodos HTTP, tais como GET, POST, PUT, PATCH e DELETE do protocolo HTTP para realizar diversas operações no servidor. Tais métodos porém podem ser bloqueados por alguns servidores e também não são permitidos em alguns navegadores (browsers) mais antigos. Para minimizar estes problemas, mantendo a maior compatibilidade possível com sistemas legados, as funcionalidades do Neo Interact CTI seguem o padrão estabelecido pelo Interact CTI utilizando apenas os métodos GET e POST.
As requisições REST são basicamente os comandos que a aplicação cliente envia ao Neo Interact CTI, não havendo na API requisições REST no sentido contrário (Neo Interact CTI ao cliente), com exceção de webhooks, caso sejam utilizados. Estas requisições são utilizadas para realizar uma série de ações tais como:
Estabelecimento de canais SSE
Assinatura de eventos
Controle dos agentes
Controle de chamadas
Consulta de configurações
Estes comandos se encontram descritos na documentação da API do Neo Interact, que utiliza o padrão OpenAPI Specification (OAS).
O modelo REST é baseado no protocolo HTTP/HTTPS, operando basicamente com requisições e respostas numa arquitetura cliente/servidor. Esta arquitetura porém não prevê a notificação de eventos assíncronos de interesse do cliente ocorridos no servidor. Para estes casos o Neo Interact CTI utiliza uma das seguintes estratégias:
Conexão persistente SSE (Server-sent events)
Webhook
SSE ou Server-sent events é uma técnica de envio de dados do servidor ao cliente através de uma conexão HTTP/HTTPS persistente. Esta tecnologia é plenamente estabelecida, padronizada e suportada na internet, dispositivos e aplicações. Por utilizar HTTP/HTTPS ela se beneficia das vantagens deste protocolo já mencionadas anteriormente, destacando-se a questão da segurança e interoperabilidade em redes.
Para manter a compatibilidade com o Interact CTI e aplicações clientes legadas, o Neo Interact CTI optou por utilizar conexões SSE (Server-sent events), ao invés de conexões websocket.
A Conexão SSE tem como principal função criar uma conexão persistente do cliente (backend/browser) com o Neo Interact. Estabelecer esta conexão não é obrigatória para se integrar ao CTI do Neo Interact, caso somente interações via requisições REST sejam suficientes.
Esta conexão é utilizada em duas situações:
Para o recebimento de notificações de eventos assíncronos do Neo Interact ao cliente (quando houver eventos assinados associados a este canal);
Para realizar login de agente específico via CTI. A conexão SSE neste caso tem a função de verificar se o agente está online (conectado) ou não.
Em caso de uso de proxies de rede, deve se assegurar que eles tenha suporte à conexão SSE.
┌───────────────────── Rede do cliente ─────────────────────┐
│ │
│ Aplicação do Cliente │
│ (Backend/Browser) NAT/Firewall │ NeoInteract
│ │
│ | | │ |
│ | | │ |
│ | Abertura de Canal SSE (HTTPS) │ | |
│ |==========================================================================>|
│ | | │ |
│ | | │ |
│ | HTTPS GET/POST (Requisiçoes REST) │ |
│ |---------------------------------------------+---------------------------->|
│ | | │ 200 OK |
│ |<--------------------------------------------+-----------------------------|
│ | | │ |
│ | | │ |
│ | | │ |
│ | | │ evento (Canal SSE) |
│ |<==========================================================================|
│ | | │ |
│ │
└───────────────────────────────────────────────────────────┘
Webhook é uma técnica na qual o servidor envia uma requisição HTTP/HTTPS de volta ao cliente para notificação de um evento, não necessitando uma conexão persistente para tal. O webhook enviado pelo Neo Interact ao cliente utiliza o método POST.
┌──────────────────── Rede do cliente ────────────────────┐
│ │
│ Aplicação do Cliente │
│ (Somente Backend) NAT/Firewall │ NeoInteract
│ │
│ | | │ |
│ | | │ |
│ | HTTPS GET/POST (Requisiçoes REST) │ |
│ |-------------------------------------------+---------------------------->|
│ | | │ 200 OK |
│ |<------------------------------------------+-----------------------------|
│ | | │ |
│ | | │ |
│ | | │ |
│ | | │ evento (POST <Webhook URL>) |
│ | |<------------+-----------------------------|
│ | | │ |
│ | (Liberação/Encaminhamento) │ |
│ | | │ |
│ | evento (POST <Webhook URL>) | │ |
│ |<----------------------------| │ |
│ | | │ |
│ │
└─────────────────────────────────────────────────────────┘
Apesar do conceito bastante simples, o webhook encontra outras questões que dificultam, ou até mesmo impedem o seu uso, tais como:
Não possui suporte em navegadores (browsers)
Necessidade de abertura da rede do cliente para recepção de requisições oriundas da internet, o que geralmente encontra problemas quando confrontados com políticas de segurança e administração de redes.
Custos e inconvenientes na configuração de dispositivos de rede do próprio cliente e segurança, como NAT's (para encaminhar os webhooks recebidos para a aplicação do cliente) e Firewalls (para liberação do acesso), bem como na análise e depuração de problemas. Normalmente este tipo de problema não ocorre nas conexões SSE, pois uma vez estabelecida esta conexão pela aplicação cliente, de dentro de sua rede para fora (Neo Interact), os eventos retornam pela mesma conexão já previamente aceita pelos dispositivos de borda da rede (NAT/Firewall). Firewalls que usam técnica DPI (Deep Inspection Package), podem ainda bloquear os eventos, no entanto numa abordagem mais padrão e convencional de segurança isso não costuma ser um problema.
Caso seja implementado controle de login do agente pela API, o webhook não atenderá o requisito da conexão persistente (SSE) para monitoramento de estado de atividade do agente.
Possibilidade de ataques maliciosos, através do recebimento de webhooks fakes.
O uso de webhooks para notificação de eventos pode gerar uma abertura para ataques à aplicação do cliente, caso um atacante produza requisições que se passam por webhooks vindos do Neo Interact, como mostra o diagrama abaixo:
┌──────────────────── Rede do cliente ────────────────────┐
│ │
│ Aplicação do Cliente │
│ (Somente Backend) NAT/Firewall │ NeoInteract Atacante
│ │
│ | | │ | |
│ | | │ | |
│ | HTTPS GET/POST (Requisiçoes REST) │ | |
│ |-------------------------------------------+---------------------------->| |
│ | | │ 200 OK | |
│ |<------------------------------------------+-----------------------------| |
│ | | │ | |
│ | | │ | |
│ | | │ | |
│ | | │ evento (POST <Webhook URL>) | |
│ | |<------------+-----------------------------| |
│ | | │ | |
│ | (Liberação/Encaminhamento) │ | |
│ | | │ | |
│ | evento (POST <Webhook URL>) | │ | |
│ |<----------------------------| │ | |
│ | | │ | |
│ | | │ evento falso (POST <Webhook URL>) |
│ | |<------------+-------------------------------------------|
│ | | │ | |
│ | (Liberação/Encaminhamento) │ | |
│ | | │ | |
│ | evento (POST <Webhook URL>) | │ | |
│ |<----------------------------| │ | |
│ | | │ | |
│ │
└─────────────────────────────────────────────────────────┘
Esses webhooks falsos podem comprometer a operação do cliente, até mesmo inviabilizar seu funcionamento. Bloqueios por IP de origem podem ser ineficientes, inclusive sob o risco de bloquear webhooks legítimos vindos do Neo Interact, uma vez que seu IP pode variar.
Como forma de mitigação deste risco, o Neo Interact adiciona a mesma API-KEY recebida nas requisições dos comandos no cabeçalho HTTP "X-API-KEY" do webhook, caso este tenha sido definido pela aplicação do cliente utilizando protocolo HTTPS. O cliente poderá validar a autenticidade do webhook, verificando a API-KEY recebida.
A API-KEY só será adicionado pelo Neo Interact quando o webhook for do tipo HTTPS, webhooks HTTP não possuirão esta chave para não expô-la em um canal não criptografado.
A API-KEY é uma chave de acesso à API CTI do Neo Interact que será abordada mais adiante nos próximos tópicos.
Uma assinatura de eventos é definida por um conjunto de eventos e seus filtros a serem enviados para a aplicação cliente. Esta assinatura deve ser renovada periodicamente e pode ser alterada conforme necessidade. Cada assinatura sempre está associada a um único canal de eventos, que pode ser uma conexão SSE ou um webhook. Somente uma assinatura por canal é permitida no Neo Interact CTI, contudo dependendo da aplicação cliente, pode haver a necessidade de se operar em múltiplos canais, cada qual com um conjunto específico de eventos. O Neo Iteract CTI permite o estabelecimento de múltiplos canais SSE e/ou múltiplos webhooks sob uma mesma API-KEY. Assim como os canais SSE, os webhooks devem ser únicos para cada assinatura, podendo diferenciar-se uns dos outros por qualquer elemento da URL. Recomenda-se que essa diferenciação seja aplicada no path dos recursos da URL para maior facilidade na operação e organização do próprio cliente. Ex:
https://cliente.saas.digitro.cloud:9999/webhook/subscription1,
https://cliente.saas.digitro.cloud:9999/webhook/subscription2,
https://cliente.saas.digitro.cloud:9999/webhook/subscription3,
...
etc