Bem vindo ao guia de integração do seu CRM com a plataforma 3C Plus.
Este documento descreve as principais funcionalidades que geralmente são integradas.
Configurações Prévias:
Antes de começar, precisamos de algumas informações da conta 3C.
- Domínio da empresa no 3C Plus
- Autenticação do Gestor:
- Token de API de um usuário gestor
- Token de API 3C Plus do agente - ou:
- Usuário e senha do agente no 3C Plus
Tipos de Acesso:
Agente (Operador): O agente é quem conecta em campanha e recebe as ligações.
Supervisor: Quem tem permissão de visualização de relatórios e algumas configurações básicas, limitadas à equipe que este supervisor estiver inserido.
Gestor: Acesso à todos os relatórios, configurações e definições da ferramenta.
Para obter o token de um usuário pode ser utilizada a endpoint abaixo:
Ou, também é possível obter o token através da interface web da 3C Plus, acessando o menu configurações -> usuários. Selecionando um usuário e abrindo as opções avançadas do mesmo.
O token de API não expira sozinho. É modificado somente por ação de um gestor.
Em todas as endpoints da API é esperado que seja informado o parâmetro api_token do usuário onde a ação deve ser realizada.
Importante:
A 3C Plus possui algumas diferenças quando comparada à maioria dos demais sistemas de telefonia do mercado:
O token de um gestor não realiza ações do agente. Não é possível, por exemplo, comandar ações de toda a operação utilizando um único token de api de gestor. Para comandar as ações de um agente é necessário informar o token do usuário em questão.
A 3C Plus não dispara webhooks. Ao invés disso, disponibilizamos tecnologia de websocket baseada em socket.io onde o CRM pode conectar-se diretamente do front-end e receber os eventos em tela para carregar ficha do cliente, mudar estado para intervalos, saber que uma chamada já foi encerrada, capturar o log de ligação finalizada, etc. Toda informação que vier da 3C Plus para o usuário chega através do socket.
Conexão com o Socket.io da 3C Plus
Para conectar-se aos eventos em tempo real, você irá precisar da biblioteca socket.io. Um exemplo de como fazer isso em Javascript:
const io = require('socket.io-client')
// Conectando ao socket
const socket = io("https://socket.3c.fluxoti.com", {
transports: ['websocket'],
query: { token: "token-da-api" }
})
// Receber eventos específicos
socket.on("agent-is-idle", function (event) {
console.log(event);
})
// Tratando possiveis erros
socket.on('error', function(err) {
console.log(err)
})Verifique nosso documento de Eventos do Socket para mais informações sobre cada um deles:
https://help.3cplus.com.br/pt-BR/articles/8575966-eventos-do-socket-3c-plus
Fluxo e Ações do Agente
Login do Agente em Uma Campanha
Para logar um agente em uma campanha é necessário primeiramente saber em qual campanha.
Para descobrir em quais campanhas o agente pode se conectar, utilizar o método:
Sugestão: Mostrar a lista combobox das campanhas que o agente pode se conectar e pedir que ele escolha uma delas. Reservar a ID da campanha selecionada. Após a seleção, liberar o botão de "Fazer login".
Para realizar o login do agente na campanha, utilize o endpoint de agent/login, informando o ID da campanha em questão.
Fazendo isso, automaticamente o agente será conectado. Desde que o mesmo esteja devidamente autenticado na tela do agente 3C Plus, onde o ramal webrtc dele estará ativo.
Caso o CRM não queira que o agente precise utilizar a tela do agente da 3C Plus, vocês podem incorporar nossas tecnologias WEBRTC diretamente na tela do CRM. Porém, existem alguns cuidados que precisam ser tomados enquanto front-end para que tudo funcione bem:
A tela do operador no CRM não poderá ser atualizada enquanto ele navegar nas opções do CRM. Assim como quando atualizamos a página do Google Meet a comunicação será interrompida e o agente será desconectado automaticamente.
A plataforma do CRM precisa estar rodando em ambiente seguro (HTTPS), para que o navegador permita o compartilhamento do microfone.
Somente o navegador Google Chrome ou outros baseados em Google Chrome (Opera, etc) estão homologados ao 3C Plus.
Além disso, é também necessário estabelecer a conexão com o Socket.io da 3C Plus, uma vez que a requisição de logar um agente é processada de maneira assíncrona, em background job, você só poderá confirmar que o login foi bem sucedido através do recebimento do evento agent-is-idle vindo do socket.
Realizar uma Chamada Manual
Para realizar uma ligação manual, primeiramente certifique-se de que o agente já está logado na campanha, conforme o processo de Login do Agente em Uma Campanha. O modo manual só pode ser iniciado se o agente estiver em estado ocioso (último evento agent-is-idle vindo do socket). Sempre passando o token do agente em questão.
O primeiro passo é utilizar o endpoint abaixo para colocar o agente em modo manual:
Após a confirmação de que o modo manual foi iniciado no agente corretamente (confirmar através do recebimento do evento "agent-entered-manual-mode" vindo do socket), você poderá então iniciar a discagem da ligação manual através do endpoint dial abaixo:
A ligação será então iniciada e a confirmação de que deu tudo certo é através do evento "call-was-connected" no evento do Socket.io.
Monitore os eventos do socket para sinalizar em tela o estado da chamada manual, "call-was-answered", "call-was-failed", "call-was-finished", etc.
Para desligar uma chamada manual, utilize o endpoint hangup abaixo, informando nele o call-id retornado no evento do socket:
Para sair do modo manual, é necessário aguardar a finalização da ligação manual que fora iniciada anteriormente. Somente quando o agente está em estado de idle em modo manual você poderá executar a endpoint de manual mode exit abaixo:
Para confirmar que a solicitação foi processada com sucesso, aguarde a chegada do evento agent-is-idle com estado de ocioso.
Intervalos (Pausas)
Assim que o agente conectar na campanha, você pode executar a endpoint abaixo para obter todas as configurações dela, isso será útil nas ações de intervalo.
Nos dados da campanha onde o operador logou, existe uma lista dos intervalos disponíveis (café, almoço, banheiro, etc). Estes intervalos são configurados pelo gestor da empresa, e as opções devem ser apresentadas ao agente para que ele escolha que tipo de intervalo quer realizar. Cada intervalo tem um limite de tempo definido, também retornado no objeto da campanha.
Você pode colocar o operador em um intervalo a qualquer momento, porém, caso o operador não esteja em estado ocioso, o intervalo será "solicitado" e iniciará automaticamente assim que o agente sair de qualquer estado que ele esteja e torne-se ocioso.
Para iniciar o intervalo utilize o endpoint abaixo, informando o ID do intervalo escolhido pelo agente.
Ao realizar a requisição acima, troque o estado do botão para "Intervalo solicitado", impedindo o agente de clicar novamente, uma vez que o intervalo será iniciado assim que possível de maneira automática.
Aguarde a chegada do evento "agent-entered-work-break" para confirmar que o agente entrou em intervalo, neste ponto, pode exibir em tela o tempo restante com a opção do operador sair do intervalo. Quando o tempo do intervalo terminar, o agente não será retirado de intervalo automaticamente, porém, uma sinalização de alerta de atraso é exibida ao gestor na dashboard da campanha.
Para sair do intervalo, utilize o endpoint abaixo:
Para confirmar que o agente saiu do intervalo, aguarde a chegada do evento do socket "agent-left-work-break" e/ou "agent-is-idle".
Fluxo da Ligação da Discadora
Agente está ocioso
Ligação foi conectada
Agente está em TPA
Agente está ocioso
Ligação Conectada
Quando o agente está ocioso, caso a campanha esteja ativa e possua uma ou mais listas de mailing com peso maior que 0, a qualquer momento poderá chegar um evento "call-was-connected" sinalizando que agora o operador está conectado com uma chamada. Dentro deste evento você deverá obter o call-id da ligação para poder realizar os comandos nela.
Na chegada deste evento, é a hora de abrir os dados do cliente com quem a chamada conectou, dentro do mesmo evento você terá os dados do mailing (com todas as informações referentes ao cliente conectado, que foram previamente importadas na lista). O campo mais importante para abertura da ficha geralmente é o "identifier", por isso recomendamos que este campo seja incluído na lista de mailing com o ID Único do cliente em seu CRM.
Por exemplo, para desligar a chamada, você deverá utilizar o endpoint abaixo informando o call-id da ligação:
Neste evento você também receberá a lista de qualificações (tabulações) disponíveis na configuração da campanha, o agente pode então selecionar uma delas.
Após encerrar a chamada, aguarde a chegada do evento "call-was-finished" e "agent-in-acw".
Importante lembrar que a qualquer momento, a chamada pode ser encerrada pelo cliente do outro lado da linha, neste caso, você também receberá o evento de "call-was-finished" e "agent-in-acw".
Qualificar Ligação
Com o call-id e o qualification-id você poderá então utilizar o endpoint abaixo para qualificar a ligação:
Caso o agente qualifique a chamada durante a ligação, ele se tornará ocioso e o próximo evento que você deve aguardar será um "agent-is-idle".
Caso o agente não qualifique a chamada antes de ela ser encerrada, o evento "agent-in-acw" chegará, sinalizando que o agente está em Tempo de Pós Atendimento (After Call Work). Este estado deve ser apresentado ao agente de forma que fique clara a necessidade de realizar a qualificação da ligação.
O TPA pode possuir um tempo limite configurável na campanha, também retornado no objeto da campanha onde o agente realizou o login.
Quando o TPA inicia, geralmente apresentamos um cronômetro sinalizando ao operador quanto tempo ainda resta para que ele realize a qualificação da chamada, caso o tempo limite esteja configurado como 0, significa que a campanha está configurada com TPA Ilimitado, não sendo necessária a apresentação do cronômetro decrescente. Assim como quando ocioso e conectado com ligação, na tela do agente da 3C Plus, apresentamos um cronômetro crescente neste caso, para que o agente saiba quanto tempo ele já permaneceu neste estado.
O endpoint de qualificar a chamada encerra o TPA imediatamente.
Caso o agente ultrapasse o tempo limite de TPA, o back-end da 3C Plus irá qualificar a chamada automaticamente como "limite de tempo excedido", com isso, o evento "agent-is-idle" será recebido, sinalizando que o agente agora está ocioso novamente aguardando a próxima ligação.
Ações do Gestor/Supervisor
Ao utlizar um token de agente ou supervisor, você poderá realizar as ações abaixo, importante ressaltar a importância de também estabelecer a conexão com o mesmo socket.io da 3C Plus descrito acima, porém, autenticando com o token de gestor/supervisor.
Ao conectar no socket da 3C Plus com token de um gestor, você receberá todos os eventos de todos os agentes e de todas as campanhas da empresa.
Ao conectar no socket da 3C Plus com token de um supervisor, você receberá todos os eventos de todos os agentes que fizerem parte da equipe onde o supervisor estiver atrelado.
Envio de Mailing
Temos um artigo em nosso help específico para este objetivo. Por favor acesse-o aqui.
Basicamente, para subir uma lista de mailing à uma campanha, você precisará saber em qual campanha será criada a lista. Utilizando o token de gestor, você tem algumas opções de como realizar essa tarefa.
Colocar um Agente em Intervalo (Pausa)
Tanto um usuário Gestor como um usuário Supervisor podem realizar a solicitação de intervalo em um agente. Para isso, é importante carregar do objeto da campanha onde o agente em questão está logado, a lista de intervalos disponíveis.
Com o token do gestor ou supervisor, utilize o endpoint abaixo passando o ID do Intervalo e o ID do Agente:
Aguarde a chegada do evento agent-entered-work-break com o ID do agente onde realizou a solicitação para sinalizar que o intervalo foi iniciado corretamente.
O gestor não pode concluir o intervalo de um agente, é necessário que o agente faça isso de sua estação, evitando que ligações sejam conectadas sem que o mesmo esteja em frente ao computador.
Da mesma maneira, é possível também desconectar um agente da campanha através do seguinte endpoint:
Obter Relatórios de Ligações
Para obter todo o tipo de retorno das ligações sem sucesso e também informações de tarifação/valor das ligações, etc. Utilize o token de um Gestor na seguinte endpoint:
Os detalhes sobre todos os parâmetros das chamadas estão descritos neste documento:
Além do endpoint Get Calls, você também pode obter dados das chamadas em tempo real através da conexão com nosso socket.
O evento ideal para realizar isso é o "call-history-was-created" que tem a mesma estrutura e os mesmos dados que uma chamada retornada no endpoint.
Caso conecte ao socket com o token de agente, este evento também é recebido, porém somente daquelas chamadas que conectaram com o agente dono do token. É o evento ideal para registrar uma ligação "sucesso" e salvar esse dado no CRM, junto à URL da gravação da ligação que também é retornada no mesmo evento.
Apesar de parecer mais complexo, aconselhamos a criação de um programa que estabeleça a conexão com o Socket 3C Plus para registro dos insucessos de maneira realtime, ao invés de realizar o pooling na endpoint Get Calls, isso torna o processo muito mais ágil e leve.