Pular para o conteúdo principal

Integrações - Conector CTI

Voipstudio CTI Connector permite a integração de uma telefonia por computador (CTI) do site ou aplicativo do cliente.

Não importa se é um simples Sistema de Gestão de Conteúdo (CMS), uma aplicação de comércio eletrônico ou um CRM (Customer Relationship Management) avançado. O Connector pode ser usado como um componente independente em quase qualquer tipo de ambiente que suporte JavaScript. O Connector suporta chamadas de saída (Click to Call, também conhecidas como c2c) e chamadas de entrada - como descrito abaixo:

  1. As conexões de saída clique para ligar à PSTN (Rede de Telefonia Tradicional) a partir do aplicativo Cliente envolvem clicar no link ou botão do número de telefone na interface do usuário que aciona a rede Voipstudio para fazer uma chamada para o terminal SIP (Telefone IP ou Softphone) registrado em a conta de usuário. Assim que a chamada for atendida, ela será transferida para o número clicado.

  2. As chamadas recebidas da PSTN (Rede de telefonia tradicional) geram notificações em tempo real sobre o estado da chamada (toque, conectado, em espera, desconectado), que deve ser tratado na interface do usuário do aplicativo do cliente.

Nos dois cenários descritos acima, uma vez estabelecida a chamada, o usuário pode controlar o estado da chamada usando a API Voipstudio CTI Connector. As conexões ativas podem ser transferidas para outro usuário do PBX ou número externo ou podem ser desconectadas.

cti-connector-diagram.png

Figure 68.1 Voipstudio Diagrama do conector.

Requerimentos​

Cti.Connector requires sip.js - Biblioteca SIP para JavaScript a ser incluído antes do código do conector. O SIP usa WebSockets para manter uma conexão bidirecional persistente com um servidor SIP que é usado como uma ponte entre o JavaScript e a rede de telefonia SIP.

Eventos do conector​

Para integrar o Conector com a sua aplicação, é necessário responder aos eventos do Cti.Connector. Para poder receber eventos e responder, precisamos passar a função que pode ser chamada como um parâmetro de configuração onMessage.

Note: O fluxo de eventos também foi descrito no exemplo de integração do Voipstudio `.

Tipos de eventos​

O Connector envia os seguintes eventos:

  • LOOGED_IN - após autenticação bem-sucedida em Voipstudio;
  • LOGGED_OUT - após o logout bem-sucedido de Voipstudio;
  • INITIAL - quando o terminal SIP caller está a tocar - ocorre apenas para chamadas OUTBOUND;
  • ACCEPTED - quando o terminal SIP do caller aceita a chamada (atende o telefone) - ocorre apenas para chamadas OUTBOUND;
  • READY - após a conexão ter sido estabelecida com o servidor SIP;
  • RINGING - quando o servidor está tentando estabelecer uma chamada OUTBOUND ou INBOUND;
  • CONNECTED - depois que a chamada OUTBOUND ou INBOUND for estabelecida com o callee;
  • ON_HOLD - quando caller ou callee coloca a chamada em espera;
  • HANGUP - quando caller ou callee desliga a chamada;
  • CANCEL - quando a chamada ainda não está conectada e ocorre um erro;
  • INFO - quando a ação não pode ser executada por algum motivo, mas o erro não ocorreu;
  • SUBSCRIBED - quando é criada uma subscrição de evento de chamada SIP;
  • ERROR - quando ocorre algum tipo de erro, por exemplo: nome de usuário e senha incorretos durante a autenticação, formato incorreto de número de telefone, ação de chamada não permitida etc.

Fluxo de eventos​

Aqui apresentamos alguns cenários típicos.

Chamada OUTBOUND:

  • INITIAL - caller Terminal SIP
  • ACCEPTED - caller Terminal SIP
  • RINGING - número marcado está a tocar
  • CONNECTED - conexão com o número marcado estabelecida
  • HANGUP - chamada terminada

Chamada INBOUND:

  • RINGING - o telefone do usuário está a tocar como resultado de uma chamada recebida
  • CONNECTED - chamada de entrada estabelecida
  • HANGUP - chamada terminada

Estrutura de eventos​

Existem dois tipos de eventos:

  • atividade eventos: LOGGED_IN, LOGGED_OUT, READY, INFO, ERROR;
  • chamada eventos: INITIAL, ACCEPTED, RINGING, CONNECTED, ON_HOLD, HANGUP, CANCEL;

Cada atividade evento enviado pelo Connector contém dois atributos:

  • name - nome do evento;
  • message - mensagem com descrição / motivo do evento;

Exemplo de eventos:

{
    nome: "READY",
    mensagem: "Connection with SIP server has been successfully established."
}

Cada evento de chamada contém igualmente dois atributos:

  • nome - nome do evento;
  • chamada - detalhes da chamada, conforme descrito abaixo;
{
    name: "CONNECTED",                      // event name
    call: {
        id: "1432310571129"                 // unique call ID
        cid: "100"                          // internal call ID used by Connector
        cause: ""                           // cause for call events: CANCEL or HANGUP
        destination: "+123456789"           // callee phone number or extension
        destinationName: "John Smith"       // callee name if available
        direction: "OUTBOUND"               // call direction: INBOUND / OUTBOUND
        source: "anonymous"                 // caller phone number if available
        sourceName: "anonymous <anonymous>" // caller name if available
        status: "CONNECTED"                 // call status
    }
}

Status de chamada disponível (o mesmo que eventos call):

  • INITIAL - quando softphone do caller está a tocar - ocorre apenas para chamadas OUTBOUND;
  • ACCEPTED - quando softphone do caller recebe a chamada (atende o telefone) - ocorre apenas para chamadas OUTBOUND;
  • RINGING - quando softphone do callee está a tocar;
  • CONNECTED - quando callee recebe a chamada (atende o telefone)
  • ON_HOLD - quando caller ou callee põe chamada em espera;
  • HANGUP - quando caller ou callee termina a chamada;

Direções de chamada disponíveis:

  • OUTBOUND - para chamadas efectuadas;
  • INBOUND - para chamadas recebidas;

Conector API​

Connector oferece API:

  • login - usado para autenticar um usuário na aplicação Voipstudio e para abrir nova conexão com o servidor SIP
  • logout - usado para sair e terminar a conexão
  • isConnected - usado para indicar se o usuário já está autenticado e conectado com Voipstudio
  • answer - usado para atender a chamada recebida no estado tocar. Nota: este método funciona apenas com Voipstudio Desktop Softphone min. v. 3.0.50
  • call - usado para fazer uma nova conexão com o número de destino
  • terminate - usado para terminar determinada chamada
  • transfer - usado para transferir uma chamada para outro número de telefone ou extensão
  • subscribe - permite criar uma subscrição para receber eventos de chamada para objectos que não sejam o utilizador com sessão iniciada.

Todos esses métodos foram descritos abaixo.

Criar conector​

Para criar a instância do Connector, precisamos definir a opção config e passá-la ao construtor:

// function that will be called whenever the connector sends event
var onMessageCallback = function(event) {
    console.info("Event received" + event.name);
    
    if (event.name === Cti.EVENT.READY) {
        document.title = "Connector is ready";
        
        // ...
    }
        
    // your code goes here
}

var connector = new Cti.Connector({
    // callback
    onMessage: onMessageCallback
});

Depois de configurar o conector, podemos começar a usar a API do conector.

login​

Parâmetros necessários:

  • username - endereço de email fornecido durante o registo em voipstudio.com
  • password - senha do usuário

ou:

  • apip_key - REST API chave atribuída à conta do usuário;

Para verificar se o usuário já está autenticado e o conector já está conectado, devemos chamar o método isConnected.

connector.isConnected(); // for now this will return false

Se o usuário ainda não estiver conectado, a primeira etapa é fazer login no aplicativo Voipstudio:

var email = "user@example.com",
    password = "secretpass";
connector.login(email, pass);

ou:

var apiKey = "%%rest_api-key%%";
connector.login(apiKey);

Após a tentativa de login, os seguintes eventos serão enviados pelo Connector:

  • LOGGED_IN - após autenticação bem sucedida;
  • READY - assim que a conexão com o servidor SIP for estabelecida;
  • ERROR - se ocorrer algum erro;

Dois factores de autenticação​

Parâmetros obrigatórios:

  • authCode - código válido de autenticação de dois factores
  • nonce - string nonce retornada pela chamada anterior ao método login.

Após a tentativa de autenticação, os seguintes eventos serão enviados pelo Connector:

  • LOGGED_IN - após autenticação bem sucedida;
  • READY - assim que a conexão com o servidor SIP for estabelecida;
  • ERROR - se ocorrer algum erro;

logout​

Se o usuário estiver autenticado e conectado, podemos desconectá-lo com o método logout:

connector.logout();

Depois disso, os seguintes eventos serão enviados pelo Connector:

  • LOGGED_OUT - após o logoff bem-sucedido;
  • ERROR - se ocorrer algum erro;

chamada​

Parâmetros necessários:

  • destination - número de telefone de destino E164 format ou extensão interna sem caracteres especiais;

Para fazer uma ligação telefônica, o método call deve ser chamado com o parâmetro de destino:

var destination = "+123456789";
connector.call(destination);

Depois disso, os seguintes eventos serão enviados pelo Connector:

  • INITIAL - quando o terminal SIP do chamador está tocando - ocorre apenas para chamadas OUTBOUND;
  • ACCEPTED - quando o ponto de extremidade SIP do chamador aceita a chamada (atende o telefone) - ocorre apenas para chamadas OUTBOUND;
  • RINGING - para informar ao aplicativo que a chamada OUTBOUND está sendo estabelecida. Durante a chamada OUTBOUND, o evento RINGING é enviado depois que o softphone chamador aceita a chamada;
  • CONNECTED - quando chamado aceita (responde) a chamada;
  • INFO - se a ação não puder ser executada;
  • ERROR - se ocorrer algum erro;

terminar​

Required parameters:

  • callId - ID de chamada exclusivo que foi recebido com eventos RINGING / CONNECTED; Esse ID deve ser armazenado para identificar futuras alterações de chamada;

Para terminar uma chamada, O método terminate deve ser chamado com o parâmetro callId:

var callId = "1432549154470";
connector.terminate(callId);

Depois disso, os seguintes eventos serão enviados pelo Connector:

  • HANGUP - após o término bem sucedido da chamada;
  • INFO - se a ação não puder ser executada;
  • ERROR - se ocorrer algum erro;

transferir​

Parâmetros necessários:

  • callId - ID de chamada exclusivo que foi recebido com eventos RINGING / CONNECTED; Esse ID deve ser armazenado para identificar futuras alterações de chamada;
  • destination - destination phone number in E164 format or internal extension without special characters;

Para transferir uma chamada para outro número de telefone ou ramal, o método transfer deve ser chamado com callId e parâmetros de destino:

var callId = "1432549154470",
    destination = "+987654321";
connector.transfer(callId, destination);

Depois disso, os seguintes eventos serão enviados por Connector:

  • HANGUP - após transferência bem sucedida da chamada;
  • INFO - se a ação não puder ser executada;
  • ERROR - se ocorrer algum erro;

Subscrever​

Parâmetros necessários:

  • node - cadeia de caracteres no formato node_type:node_id que descreve o objeto que queremos subscrever para chamar eventos.

Os valores válidos de node_type são:

* `user`
* `ivr`
* `queue`
* `conf`

Por exemplo, para subscrever os eventos de chamada do utilizador ID 12345:

connector.subscribe('user:12345');

Após uma subscrição bem sucedida, os seguintes eventos serão enviados pelo Connector:

  • SUBSCRIBED - após a subscrição bem sucedida;
  • ERROR - se ocorrer algum erro;

getSubscriptionURIs​

Retorna o array de URIs de assinaturas de eventos de chamada ativos, por exemplo:

var subscriptions = connector.getSubscriptionURIs();
console.log(subscriptions);
$ [ '10002@eu.sip.ssl7.net', 'conf:123456@eu.sip.ssl7.net' ]

Implementação de exemplo - Cti.Platform​

Para um melhor entendimento, criamos uma implementação de exemplo que usa o Cti.Connector para criar a interface do usuário Click to call e mostrar como é fácil integrá-la. O código de exemplo pode ser encontrado em CTI Connector.

cti-connector-example-integration.png

Figure 68.2 Voipstudio Connector example integration.

A imagem acima mostra cinco etapas:

  1. Pronto para plataforma: Connector e outros arquivos JavaScript foram carregados com sucesso, o usuário ainda não está autenticado; O primeiro passo é conectar-se ao aplicativo Voipstudio via Cti.Connector. Isso requer o fornecimento de endereço de e-mail e senha válidos da sua conta Voipstudio; A inserção de dados inválidos acionará o evento ERROR com a mensagem adequada;
  2. O conector agora está READY: após a autenticação bem-sucedida, recebemos o evento LOGGED_IN e, mais tarde, após a conexão ter sido estabelecida, o conector enviou o evento READY - agora estamos prontos para fazer chamadas de saída e receber chamadas INBOUND;
  3. Fazendo chamadas de saída: após digitar o número do telefone e clicar no botão Chamada de saída, o Connector enviou o evento INITIAL. Isso significa que o softphone chamador está tocando e aguarda a aceitação da chamada. Isso ocorre apenas para chamadas OUTBOUND;
  4. Depois de aceitar a chamada por chamador (atendendo o telefone), o Connector envia o evento ACCEPTED. Agora o processo de toque pode começar. Se destinatário não pôde aceitar a chamada, estava ocupado ou inacessível, o Connector enviará o evento CANCEL com a propriedade cause adequada. Isso ocorre apenas para chamadas OUTBOUND;
  5. O Connector enviou o evento RINGING para notificar nosso aplicativo que está tentando estabelecer uma nova conexão - o telefone callee agora está tocando; Se a conexão não puder ser estabelecida, o evento ERROR com mensagem adequada será retornado;
  6. Recebendo uma chamada INBOUND: quando a conexão estiver sendo estabelecida, o conector enviará o evento RINGING com as informações caller. Essas informações podem ser usadas, por exemplo, para identificar chamador, abrir o histórico de chamadas ou exibir detalhes de chamador;
  7. Connector in now CONNECTED: quando callee atender nossa chamada OUTBOUND ou após atender a chamada INBOUND, o conector enviará o evento CONNECTED, o que significa que a chamada foi estabelecida. Tendo uma chamada ativa, podemos encerrá-la ou transferir para outro número de telefone. Depois de encerrar ou transferir a chamada, retornaremos à etapa

Recomendamos que você se familiarize com esta implementação.

Nós o chamamos de Cti.Platform, pois contém todo o código necessário para integrar o Cti.Connector com o exemplo de criação de aplicativo com o Bootstrap. Com este código de exemplo, você pode se autenticar no aplicativo Voipstudio e fazer, transferir e encerrar chamadas. Essa funcionalidade básica pode ser facilmente estendida, dependendo das necessidades do cliente.