Integração com o 3C Plus - Completo | 3C Plus | Help Center

Integração com o 3C Plus - Completo

Guia para desenvolvimento de integração do seu sistema com a 3C Plus

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.

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

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.

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:

1. Via endpoint: POST /authenticate

2. Interface Web: Acesse o painel 3C Plus em Configurações → Usuários, selecione o usuário desejado e abra as opções avançadas.

Via endpoint:

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

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:

• GET /agent/campaigns

Apresente essas campanhas ao agente (por exemplo, em um combobox). Após selecionar a campanha, use:

• POST /agent/login

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-idle enviado pelo socket.

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-idle enviado 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.
​
​Lembre-se: Ao carregar o Extension via iframe, utilize o atributo allow="microphone" para garantir que a permissão seja concedida.

A ordem recomendada para uso é:

1. Carregar o ramal (URL acima, substituindo {dominio} e {token_do_agente})

2. Conectar no Socket.io

3. Chamar o endpoint POST /agent/login

4. Aguardar a chegada do evento no Socket:

   • agent-is-idle (login com sucesso)

   • agent-login-failed (login falhou).

Carregar o ramal (URL acima, substituindo {dominio} e {token_do_agente})

Conectar no Socket.io

Chamar o endpoint

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

1. Iniciar modo manual:

   • POST /agent/manual_call_enter

   • Aguarde o evento agent-entered-manual-mode via socket.

2. Discar para o número:

   • POST /agent/manual_call_dial

   • A confirmação de conexão ocorre via evento call-was-connected.

3. Para desligar a chamada:

   • POST /agent/call/{call_id}/hangup

4. Ao terminar, se o agente estiver novamente ocioso em modo manual, saia do modo manual:

   • POST /agent/manual_call_exit

   • Confirme o evento agent-is-idle.

Iniciar modo manual:

Aguarde o evento agent-entered-manual-mode via 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:

• GET /campaigns/agent/loggedCampaign

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:

• POST /agent/work_break/{work_break_id}/enter

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:

• POST /agent/work_break_exit

E aguarde agent-left-work-break ou agent-is-idle.

4. Fluxo da Ligação da Discadora

1. Agente está ocioso - evento agent-is-idle

2. Ligação foi conectada – evento call-was-connected

3. Agente está em TPA – evento agent-in-acw após call-was-finished

4. Agente está ocioso - evento agent-is-idle

Agente está ocioso - evento agent-is-idle

Ligação foi conectada – evento call-was-connected

Agente está em TPA – evento agent-in-acw após call-was-finished

Agente 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 chamadas

• mailing.data - Dados do cliente (nome, número, ...)

• qualifications - Lista de qualificações disponíveis

call.id - ID único da ligação - Necessário para comandos nas chamadas

mailing.data - Dados do cliente (nome, número, ...)

qualifications - Lista de qualificações disponíveis

Para desligar a chamada:

• POST /agent/call/{call_id}/hangup

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:

• POST /agent/call/{call_id}/qualify

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.

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:

• POST /agent/work_break/{work_break_id}/enter

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

• POST /agent/logout

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:

• GET /calls

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.

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:

• Documentação Oficial

• Help Center 3C Plus

Documentação Oficial

Help Center 3C Plus

Ótimas integrações e um excelente desenvolvimento!