Przejdź do treści

Integracje - CTI Connector

VoIPstudio CTI Connector umożliwia integrację telefonii komputerowej (CTI) strony internetowej lub aplikacji klienta.

Nie ma znaczenia, czy jest to prosty system zarządzania treścią (CMS), aplikacja e-commerce, czy zaawansowane zarządzanie relacjami z klientami (CRM). Connector może być używany jako samodzielny komponent w prawie każdym środowisku obsługującym JavaScript. Oprogramowanie sprzęgające obsługuje zarówno połączenia wychodzące (kliknij, aby połączyć znane również jako c2c), jak i połączenia przychodzące - zostało to opisane poniżej:

1) Wychodzące połączenia typu kliknij, aby zadzwonić do PSTN (tradycyjnej sieci telefonicznej) z poziomu aplikacji klienta obejmują kliknięcie łącza lub przycisku z numerem telefonu w interfejsie użytkownika, który uruchamia sieć VoIPstudio w celu nawiązania połączenia z punktem końcowym SIP (telefon IP lub telefon programowy) zarejestrowanym na koncie użytkownika. Po odebraniu tego połączenia jest ono przekazywane na kliknięty numer.

2) Połączenia przychodzące odbierane z sieci PSTN (tradycyjną sieć telefoniczna) generują w czasie rzeczywistym powiadomienia o stanie połączenia (dzwonienie, połączenie, zawieszenie, rozłączenie), które powinny być obsługiwane w interfejsie użytkownika aplikacji klienta. W obu opisanych powyżej scenariuszach po nawiązaniu połączenia użytkownik może kontrolować stan połączenia za pomocą VoIPstudio CTI Connector API. Bieżące połączenia można przenieść na innego użytkownika PBX lub numer zewnętrzny albo rozłączyć.

cti-connector-diagram.png

Figure 57.1 VoIPstudio Connector - schemat.

Wymagania

Cti.Connector wymaga sip.js - biblioteki SIP dla JavaScript, która ma być dołączona przed kodem złącza. SIP używa WebSockets do utrzymywania trwałego dwukierunkowego połączenia z serwerem SIP, który jest używany jako pomost między JavaScript i siecią telefoniczną SIP.

Connector - zdarzenia

Aby zintegrować Connector w swojej aplikacji, musisz odpowiadać na zdarzenia z Cti.Connector. Aby móc odbierać zdarzenia i odpowiadać na nie, musimy przekazać wywoływalną funkcję jako parametr konfiguracyjny onMessage.

Uwaga: Przebieg zdarzeń został również opisany w przykładowej integracji VoIPstudio.

Rodzaje zdarzeń

Connector wysyła nastepujące zdarzenia:

  • LOOGED_IN - po pomyślnym uwierzytelnieniu w VoIPstudio;
  • LOGGED_OUT - po pomyślnym wylogowaniu się z VoIPstudio;
  • INITIAL - kiedy punk końcowy SIP caller dzwoni - występuje tylko dla połączeń OUTBOUND;
  • ACCEPTED - kiedy punk końcowy SIP caller odbiera połączenie (odbiera telefon) - występuje tylko dla połączeń OUTBOUND;
  • READY - po nawiązaniu połączenia z serwerem SIP;
  • RINGING - gdy serwer próbuje nawiązać połączenie OUTBOUND lub INBOUND;
  • CONNECTED - po nawiązaniu połączenia OUTBOUND lub INBOUND z callee;
  • ON_HOLD - kiedy caller lub callee zawiesza połączenie;
  • HANGUP - kiedy caller lub callee kończy rozmowę;
  • CANCEL - gdy połączenie nie zostało jeszcze nawiązane i wystąpił błąd;
  • INFO - gdy z jakiegoś powodu nie można wykonać akcji, ale błąd nie wystąpił;
  • ERROR - gdy wystąpi jakikolwiek błąd, na przykład: nieprawidłowa nazwa użytkownika i hasło podczas uwierzytelniania, nieprawidłowy format numeru telefonu, niedozwolona akcja telefoniczna itp.

Przepływ zdarzeń

Oto kilka typowych scenariuszy.

OUTBOUND call:

  • INITIAL - caller SIP endpoint
  • ACCEPTED - caller SIP endpoint
  • RINGING - wybrany numer dzwoni
  • CONNECTED - nawiązano połączenie z wybieranym numerem
  • HANGUP - połączenie zakończone

INBOUND call:

  • RINGING - telefon użytkownika dzwoni w wyniku połączenia przychodzącego
  • CONNECTED - nawiązano połączenie przychodzące
  • HANGUP - połączenie zakończone

Struktura zdarzeń

Sa dwa typy zdarzeń:

  • zdarzenia typu activity: LOGGED_IN, LOGGED_OUT, READY, INFO, ERROR;
  • zdarzenia typucall: INITIAL, ACCEPTED, RINGING, CONNECTED, ON_HOLD, HANGUP, CANCEL;

Każde activity wysłane przez Connector zawiera dwa atrybuty:

  • name - nazwa zdarzenia;
  • message - wiadomość z opisem / przyczyną zdarzenia;

Przykładowe zdarzenia:

{
    name: "READY",
    message: "Connection with SIP server has been successfully established."
}

Każde zdarzenie typu call zawiera również dwa atrybuty::

  • name - nazwa zdarzenia;
  • call - szczegóły połączenia, jak opisano poniżej;
{
    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
    }
}

Dostępne statusy połączeń (tak samo jak zdarzenia typu call):

  • INITIAL - kiedy caller softphone dzwoni - występuje tylko dla połączeń OUTBOUND;
  • ACCEPTED - kiedy caller odbiera połączenie (odbiera telefon) - występuje tylko dla połączeń OUTBOUND;
  • RINGING - kiedy callee softphone dzwoni;
  • CONNECTED - kiedy callee akceptuje połączenie (odbiera telefon)
  • ON_HOLD - kiedy caller lub callee zawiesza połączenie;
  • HANGUP - kiedy caller lub callee kończy połączenie;

Dostępne kierunki połączeń:

  • OUTBOUND - dla połączeń wychodzących;
  • INBOUND - dla połączeń przychodzących;

Connector API

Connector oferuje API:

  • login - służy do uwierzytelniania użytkownika w aplikacji VoIPstudio i do otwierania nowego połączenia z serwerem SIP
  • logout - służy do wylogowywania i zamykania połączenia
  • isConnected - służy do wskazania, czy użytkownik jest już uwierzytelniony i połączony z VoIPstudio
  • answer - używany do odbierania połączeń przychodzących w stanie dzwonienia. Uwaga: ta metoda działa tylko z naszym softphone VoIPstudio min. v. 3.0.50
  • call - używany do tworzenia nowego połączenia z numerem docelowym
  • terminate - służy do zakończenia danego połączenia
  • transfer - służy do przekazywania danego połączenia na inny numer telefonu lub wewnętrzny

Wszystkie te metody zostały opisane poniżej.

Connector Tworzenie

Aby stworzyć instancję Connector musimy ustawić opcję config i przekazać ją do konstruktora:

// 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
});

Po skonfigurowaniu konektora możemy zacząć korzystać z api konektora.

logowanie

Wymagane parametry:

  • username - adres e-mail podany podczas rejestracji w voipstudio.pl
  • password - hasło użytkownika

lub:

  • apip_key - REST API klucz przypisany do konta użytkownika;

Aby sprawdzić, czy użytkownik jest już uwierzytelniony, a konektor już podłączony, należy wywołać metodę isConnected. 

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

If user is not yet connected, the first step is to login into VoIPstudio app:

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

or:

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

Po próbie zalogowania się przez Konektor zostaną wysłane następujące zdarzenia:

  • LOGGED_IN - po pomyślnym uwierzytelnieniu;
  • READY - gdy tylko zostanie nawiązane połączenie z serwerem SIP;
  • ERROR - jeśli wystąpi jakikolwiek błąd;

wylogowanie

Jeśli użytkownik jest uwierzytelniony i połączony, możemy go rozłączyć metodą logout:

connector.logout();

Następnie przez Konektor zostaną wysłane następujące zdarzenia:

  • LOGGED_OUT - po pomyślnym wylogowaniu;
  • ERROR - jeśli wystąpi jakikolwiek błąd;

połączenie

Wymagane parametry:

  • destination - numer docelowy w formacie E164 format lub nr wewnętrzny bez żadnych znaków specjalnych;

Aby wykonać połączenie telefoniczne należy wywołać metodę call z parametrem destination:

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

Następnie przez Konektor zostaną wysłane następujące zdarzenia:

  • INITIAL - kiedy caller softphone dzwoni - występuje tylko dla połączeń OUTBOUND;
  • ACCEPTED - kiedy caller odbiera połączenie (odbiera telefon) - występuje tylko dla połączeń OUTBOUND;
  • RINGING - aby poinformować aplikację, że nawiązywane jest połączenie OUTBOUND. Podczas połączenia OUTBOUND zdarzenie RINGING jest wysyłane kiedy caller odbiera połączenie (odbiera telefon);
  • CONNECTED - kiedy callee akceptuje połączenie (odbiera telefon)
  • INFO - jeśli akcja nie może zostać wykonana;
  • ERROR - jeśli wystąpi jakikolwiek błąd;

zakończenie

Wymagane parametry:

  • callId - unikalny identyfikator połączenia, który został odebrany ze zdarzeniami RINGING / CONNECTED; Ten identyfikator powinien być przechowywany w celu identyfikacji przyszłych zmian połączeń;

Aby zakończyć dane połączenie należy wywołać metodę terminate z parametremcallId:

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

Następnie przez Konektor zostaną wysłane następujące zdarzenia:

  • HANGUP - po pomyślnym zakończeniu połączenia;
  • INFO - jeśli akcja nie może zostać wykonana;
  • ERROR - jeśli wystąpi jakikolwiek błąd;

transfer

Wymagane parametry:

  • callId - unikalny identyfikator połączenia, który został odebrany ze zdarzeniami RINGING / CONNECTED; Ten identyfikator powinien być przechowywany w celu identyfikacji przyszłych zmian połączeń;
  • destination - numer docelowy w formacie E164 format lub nr wewnętrzny bez żadnych znaków specjalnych;

Aby przetransferować połączenie do innego numeru lub numeru wewnętrznego należy wywołać metodę transfer z parametrem callId i parametrem docelowym:

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

Następnie przez Konektor zostaną wysłane następujące zdarzenia:

  • HANGUP - po pomyślnym wykonaniu transferu;
  • INFO - jeśli akcja nie może zostać wykonana;
  • ERROR - jeśli wystąpi jakikolwiek błąd;

Przykładowa implementacja - Cti.Platform

Aby lepiej zrozumieć, stworzyliśmy przykładową implementację, która wykorzystuje Cti.Connector do stworzenia interfejsu użytkownika typu Kliknij, aby zadzwonić i pokazania, jak łatwo jest go zintegrować. Przykładowy kod można znaleźć w repozytorium CTI Connector.

cti-connector-example-integration.png

Figure 57.2 VoIPstudio Konektor - przykładowa integracja

Powyższy obraz przedstawia pięć kroków:

  1. Platforma gotowa: Connector i inne pliki JavaScript zostały pomyślnie załadowane, użytkownik nie jest jeszcze uwierzytelniony; Pierwszym krokiem jest połączenie się z aplikacją VoIPstudio przez Cti.Connector. Wymaga to podania prawidłowego adresu e-mail i hasła z konta VoIPstudio; Wprowadzenie błędnych danych wywoła zdarzenie ERROR z odpowiednim komunikatem;
  2. Konektor ma teraz status READY: po pomyślnym uwierzytelnieniu otrzymaliśmy zdarzenie LOGGED_IN, później po niawiązaniu połączenia konektor wysyła zdarzenie READY - jesteśmy teraz gotowi do wykonywania połączeń wychodzących i odbierania połączeń przychodzących;
  3. Wykonywanie połączenia wychodzącego: po wprowadzeniu numeru telefonu i kliknięciu przycisku Outbound call, Konektor wysyła zdarzenie INITIAL. Oznacza to, że caller's softphone dzwoni i oczekuja na zaakceptowanie połączenia Dzieje się tak tylko w przypadku połączeń OUTBOUND;
  4. Po zaakceptowaniu połączenia caller (odebraniu telefonu), Konektor wysyła zdarzenie ACCEPTED. Teraz można rozpocząć dzwonienie. Jeśli callee nie może zaakceptowac połączenia, był zajety lub niedostepny, Konektor wyśle zdarzenie CANCEL z odpowiednią włąściwością cause. Dzieje się tak tylko w przypadku połączeń OUTBOUND;
  5. Konektor wysłał zdarzenieRINGING, aby powiadomić naszą aplikację, że próbuje nawiązać nowe połączenie - telefon callee teraz dzwoni; Jeśli nie udało się nawiązać połączenia, zwrócone zostanie zdarzenie ERROR z odpowiednim komunikatem;
  6. Odbieranie połączenia INBOUND: podczas nawiązywania połączenia, konektor wyśle zdarzenie RINGING z informacją caller. Informacje te mogą służyć na przykład do identyfikacji caller, ootwierania historii połączeń lub wyświetlania detali dla caller; 7.Konektor ma status CONNECTED:kiedy callee odbierze nasze połączenie OUTBOUND lub po odebraniu połączenia INBOUND, konektor wyśle zdarzenie CONNECTED co oznacza, że połączenie zostało nawiązane. Mając aktywne połączenie możemy je zakończyć lub przetransferować na inny numer telefonu. Po zakończeniu lub przekazaniu połączenia wrócimy do kroku 1. Zachęcamy do zapoznania się z tym przykładem implenetacji.

Nazywamy to Cti.Platform ponieważ zawiera cały kod niezbędny do integracji Cti.Connector z przykładową kompilacją aplikacji przy użyciu Bootstrap. Za pomocą tego przykładowego kodu możesz uwierzytelniać się w aplikacji VoIPstudio oraz wykonywać, transferować i przerywać połączenia. Tę podstawową funkcjonalność można łatwo rozszerzyć w zależności od potrzeb klienta.