Bem-vindo ao nosso guia, dev!
Aqui você encontrará tudo o que precisa para integrar o seu CRM à plataforma 3C Plus de maneira prática e sem complicações. Prepare-se para aprender sobre configurações iniciais, fluxos de ligação e algumas das ações de gestor e supervisor.
Este documento foi pensado como um guia introdutório, esclarecendo como tudo funciona e fornecendo uma integração inicial que pode ser expandida futuramente.
Recomendamos fortemente que sua integração seja desenvolvida a partir do que está descrito aqui, pois esta base é fundamental para o funcionamento do sistema.
Antes de começar é ideal que você receba o treinamento do nosso time de implantação para entender como a plataforma funciona, isso é essencial para facilitar o processo de entendimento do fluxo de configurações.
Ao final deste documento, você deve conseguir realizar o fluxo completo de um Agente utilizando o 3C Plus:
Como agente:
Logar em uma campanha;
Conectar, qualificar e desligar chamadas da discadora e receptivas;
Realizar ligações manuais;
Entrar e saír de intervalos.
Como gestor:
Colocar um agente em intervalo;
Desconectar um agente;
Obter relatório de ligações.
Bora por a mão na massa? :D
Configurações Prévias
Antes de começar, precisamos de algumas informações da conta 3C Plus:
Domínio da empresa no 3C Plus: Este domínio é a base principal que você usa para enviar requisições. É o domínio usado para acessar sua empresa, por exemplo:
minha-empresa.3c.plus.Autenticação do Gestor:
Token de API de um usuário gestor
Token de API ou Usuário e Senha de um usuário agente
Tipos de Acesso
Agente: Conecta-se a uma campanha, realiza e recebe as ligações.
Supervisor: Permissão de visualização de relatórios e algumas configurações, limitadas à equipe vinculada a ele.
Gestor: Acesso total a relatórios, configurações e definições da ferramenta.
Obtendo o Token
Para obter o token de um usuário, há duas opções:
Via endpoint:
POST /authenticateInterface Web: Acesse o painel 3C Plus em Configurações → Usuários, selecione o usuário desejado e abra as opções avançadas.
Importante: O token de API não expira sozinho. Ele é alterado somente por ação de um gestor. Em todas as chamadas da API, informe o api_token do usuário cujas ações devem ser executadas.
Atenção ao token de gestor: O token de um usuário gestor não realiza ações em nome de um agente. Para comandar as ações de um agente específico, é preciso informar o próprio token daquele agente.
Comparativo de Webhooks e Socket.io
A 3C Plus não dispara webhooks. Em vez disso, disponibiliza uma conexão WebSocket via Socket.io, pela qual o seu sistema recebe eventos em tempo real. Isso significa que toda informação da 3C Plus para o usuário chegará por meio de eventos de socket.
Observação Importante sobre Respostas HTTP e Eventos no Socket
Vários endpoints da 3C Plus podem retornar HTTP 204 (sem conteúdo) para indicar que a requisição foi recebida e será processada em segundo plano. Nesse caso, a confirmação efetiva de sucesso ou falha aparece por meio dos eventos do socket (como agent-is-idle, agent-login-failed, call-was-finished, etc.). Portanto, é essencial ficar atento aos eventos do Socket.io para saber se a ação realmente deu certo.
Conexão com o Socket.io
Para conectar-se à 3C Plus e receber eventos em tempo real, você precisará da biblioteca Socket.io. Segue um exemplo de como fazer isso em JavaScript:
const io = require('socket.io-client');
// Conectando ao socket
const socket = io("https://socket.3c.plus", {
transports: ['websocket'],
query: { token: "token-da-api" },
});
// Receber eventos específicos
socket.on("agent-is-idle", function (event) {
console.log(event);
});
// Tratando possíveis erros
socket.on('error', function(err) {
console.log(err);
});Para mais informações sobre cada evento, consulte o artigo de Eventos do Socket.
Fluxo e Ações do Agente
1. Login do Agente em Uma Campanha
Antes de tudo, descubra em quais campanhas o agente pode se conectar:
Apresente essas campanhas ao agente (por exemplo, em um combobox). Após selecionar a campanha, use:
Isso conecta o agente na campanha, desde que ele esteja autenticado na tela do agente 3C Plus (onde o ramal WebRTC dele está ativo) ou que você tenha incorporado a tecnologia WebRTC diretamente em seu CRM.
Considerações para incorporação do WebRTC no CRM
A interface do agente no CRM não pode ser recarregada, pois isso derrubaria a ligação (assim como acontece em aplicativos de videoconferência).
O CRM deve estar em ambiente seguro (HTTPS) para o navegador permitir acesso ao microfone.
Somente navegadores baseados em Chrome (Opera, etc.) são homologados.
O login do agente é assíncrono: para confirmar que deu tudo certo, aguarde o evento
agent-is-idleenviado pelo socket.
URL para incorporar o WebRTC
Caso queira incorporar a solução de voz WebRTC no seu sistema, sem utilizar a tela do agente 3C Plus, disponibilizamos uma URL específica para facilitar os trabalhos:
https://{dominio}.3c.plus/extension?api_token={token_do_agente}`
Carregando essa URL no seu sistema (por exemplo, em um iframe ou em uma nova janela) e passando o token do usuário do tipo agente, o extension registra automaticamente o ramal no WebRTC, permitindo que o agente receba a chamada de login na campanha.
Ele oferece apenas as funções básicas de registro e aceite da ligação, além de um botão para ativar ou desativar o microfone (mute). Quaisquer outras funcionalidades, como login, logout, qualificar e encerrar ligação, entrar e sair de intervalos, devem ser implementadas via API.
A ordem recomendada para uso é:
Carregar o ramal (URL acima, substituindo
{dominio}e{token_do_agente})Conectar no Socket.io
Chamar o endpoint
POST /agent/loginAguardar a chegada do evento no Socket:
agent-is-idle(login com sucesso)agent-login-failed(login falhou).
A ligação de conexão enviada pelo agent/login só é efetivada se o ramal do agente estiver registrado e aceitar essa chamada.
2. Realizar uma Chamada Manual
Verifique se o agente está logado na campanha e em estado ocioso (último evento agent-is-idle). Sempre passe o token do agente:
Iniciar modo manual:
Aguarde o evento
agent-entered-manual-modevia socket.
Discar para o número:
A confirmação de conexão ocorre via evento
call-was-connected.
Para desligar a chamada:
Ao terminar, se o agente estiver novamente ocioso em modo manual, saia do modo manual:
Confirme o evento
agent-is-idle.
3. Intervalos (Pausas)
Após logar o agente, utilize:
Nesse retorno, você encontra a lista de intervalos (pausas) disponíveis na campanha (café, almoço, etc.). Cada intervalo possui um ID e um limite de tempo configurados pelo gestor.
Para iniciar o intervalo:
Aguarde o evento agent-entered-work-break. Quando o tempo do intervalo termina, o sistema não retira o agente automaticamente, mas sinaliza atraso ao gestor. Para sair do intervalo, use:
E aguarde agent-left-work-break ou agent-is-idle.
4. Fluxo da Ligação da Discadora
Agente está ocioso - evento
agent-is-idleLigação foi conectada – evento
call-was-connectedAgente está em TPA – evento
agent-in-acwapóscall-was-finishedAgente está ocioso - evento
agent-is-idle
Quando uma ligação é conectada ao agente, dentro do evento call-was-connected você recebe:
call.id- ID único da ligação - Necessário para comandos nas chamadasmailing.data- Dados do cliente (nome, número, ...)qualifications- Lista de qualificações disponíveis
Para desligar a chamada:
Ao encerrar a chamada, chegará o evento call-was-finished.
Se não houver qualificação, o agente entra em TPA.
Para qualificar a chamada:
Se o agente qualificar durante a ligação, ele fica ocioso em seguida. Se a chamada terminar sem qualificação, o evento agent-in-acw sinaliza TPA (Tempo Pós Atendimento ou After Call Work).
Esse TPA pode ter tempo limite configurável (ou ser ilimitado). Quando o limite expira, a chamada é automaticamente qualificada como “limite de tempo excedido”, e o agente volta para ocioso.
Ações do Gestor/Supervisor
Autentique-se com token de gestor ou supervisor para controlar todos os agentes.
Token do Gestor: Eventos de todos os agentes e campanhas.
Token do Supervisor: Eventos de todos os agentes da(s) equipe(s) atribuída(s) a ele.
1. Envio de Mailing
Consulte o artigo Mailing na 3C Plus para ver como subir listas de contatos a uma campanha.
2. Colocar Agente em Intervalo (Pausa)
Com o token de gestor ou supervisor, use:
Basta informar o ID do intervalo e o ID do agente. Acompanhe o evento agent-entered-work-break.
Observação: O gestor não pode encerrar o intervalo de um agente; apenas o próprio agente pode fazê-lo, garantindo que ninguém seja posto em ligação sem estar pronto.
3. Desconectar um Agente da Campanha
Ao fazer isso, o agente é removido da campanha e não receberá mais chamadas.
4. Obter Relatórios de Ligações
Para obter o histórico completo de chamadas, utilize:
Se quiser dados em tempo real, conecte-se ao socket com o token de gestor e acompanhe o evento call-history-was-created, que traz as mesmas informações.
Caso se conecte com o token de um agente, você receberá esse evento apenas para as chamadas daquele agente.
Dica: Criar um serviço para registrar ligações via socket em tempo real pode ser mais ágil do que fazer requisições de pool frequentes em GET /calls.
Conclusão
Com este guia completo, você tem as principais referências para integrar seu CRM ao 3C Plus, desde a configuração inicial até o envio de mailings e acompanhamento de relatórios.
Use o token correto (gestor ou agente) para cada situação.
Conecte seu CRM ao Socket.io para receber eventos em tempo real.
Implemente o fluxo do agente (login, pausa, ligações manuais e discagem automática) de forma integrada.
Monitore e gerencie a operação com as ações de gestor e supervisor.
Lembre-se de que vários endpoints podem retornar HTTP 204, e a confirmação de sucesso ou falha acontecerá via eventos do Socket.io.
Para mais detalhes, consulte:
Ótimas integrações e um excelente desenvolvimento!