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.

Figure 61.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.

Parâmetros necessários:

username - endereço de email fornecido durante o registo em voipstudio.pt
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árioClick to call e mostrar como é fácil integrá-la. O código de exemplo pode ser encontrado em CTI Connector.

Figure 61.2 VoIPstudio Connector example integration.

A imagem acima mostra cinco etapas:

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;
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;
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;
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;
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;
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;
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.

Integrações - Conector CTI¶

Requerimentos¶

Eventos do conector¶

Tipos de eventos¶

Fluxo de eventos¶

Estrutura de eventos¶

Conector API¶

Criar conector¶

login¶

Dois factores de autenticação¶

logout¶

chamada¶

terminar¶

transferir¶

Subscrever¶

getSubscriptionURIs¶

Implementação de exemplo - Cti.Platform¶