Integrationen - CTI-Anschluss¶

VoIPstudio CTI Connector ermöglicht die Computer-Telefonie-Integration (CTI) der Kundenwebsite oder -anwendung. Es spielt keine Rolle, ob es sich um ein einfaches Content Management System (CMS), eine E-Commerce-Anwendung oder ein erweitertes Customer Relationship Management (CRM) handelt. Connector kann als eigenständige Komponente in nahezu jeder Umgebung verwendet werden, die JavaScript unterstützt. Der Connector unterstützt sowohl ausgehende (Click-to-Call) als auch eingehende Anrufe (siehe unten):

1) Ausgehende Click-to-Call-Verbindungen zu PSTN (Traditional Telephony Network) in der Kundenanwendung umfassen das Klicken auf den Link oder die Schaltfläche der Telefonnummer in der Benutzeroberfläche, wodurch das Netzwerk von VoIPstudio dazu veranlasst wird, einen Anruf an den SIP-Endpunkt (IP-Telefon oder Softphone) zu tätigen, der im Benutzerkonto registriert ist. Sobald dieser Anruf entgegengenommen wird, wird er an die angeklickte Nummer weitergeleitet.

2) Eingehende Anrufe, die vom PSTN (Traditional Telephony Network) empfangen werden, erzeugen Echtzeitbenachrichtigungen über den Anrufstatus (Klingeln, Verbunden, Halten, Unterbrochen), die in der Benutzeroberfläche der Kundenanwendung verarbeitet werden sollen.

In beiden oben beschriebenen Szenarien kann der Benutzer den Anrufstatus mit der API VoIPstudio CTI Connector steuern, sobald der Anruf hergestellt wurde. Laufende Verbindungen können an einen anderen PBX-Benutzer oder eine externe Nummer übertragen oder getrennt werden.

Figure 57.1 VoIPstudio Connector diagram.

Anforderungen¶

Cti.Connector erfordert sip.js - SIP-Bibliothek für JavaScript, die vor dem Connector-Code eingefügt werden soll. SIP verwendet WebSockets, um eine dauerhafte bidirektionale Verbindung zu einem SIP-Server aufrechtzuerhalten, der als Brücke zwischen JavaScript und SIP-Telefonnetz verwendet wird.

Connector's Events¶

Um Connector in Ihre Anwendung zu integrieren, müssen Sie auf Cti.Connector Events antworten. Um Events zu empfangen und beantworten zu können, müssen wir eine aufrufbare Funktion als Konfigurationsparameter onMessage übergeben.

Hinweis: Der Event flow wurde auch in VoIPstudio Beispielintegration beschrieben.

Typen von Events¶

Connector sendet (feuert) die folgenden Events:

LOOGED_IN - nach erfolgreicher Authentifizierung bei VoIPstudio;
LOGGED_OUT - nach erfolgreicher Abmeldung von VoIPstudio;
INITIAL - wenn der SIP-Endpunkt des Anrufers klingelt - tritt nur bei ausgehenden Anrufen auf.
ACCEPTED - wenn Anrufer SIP-Endpunkt den Anruf annimmt (den Hörer abhebt) - tritt nur bei ausgehenden Anrufen auf;
READY - nachdem die Verbindung zum SIP-Server hergestellt wurde;
RINGING - wenn der Server versucht, einen OUTBOUND- oder INBOUND-Anruf herzustellen;
CONNECTED - nachdem mit * 'Angerufener' * ein OUTBOUND- oder INBOUND-Anruf hergestellt wurde;
ON_HOLD - wenn Anrufer oder Angerufene den Anruf unterbrechen;
HANGUP - wenn der Anrufer oder der Angerufene den Anruf beendet;
CANCEL - wenn der Anruf noch nicht verbunden ist und ein Fehler auftritt;
INFO - wenn die Aktion aus irgendeinem Grund nicht ausgeführt werden kann, dein Fehler jedoch nicht aufgetreten ist;
SUBSCRIBED - wenn ein SIP-Anrufereignis erstellt wird;
ERROR - Wenn ein Fehler auftritt, z. B. ein falscher Benutzername und ein falsches Kennwort während der Authentifizierung, ein falsches Telefonnummernformat, eine nicht zulässige Anrufaktion usw.

Event Flow¶

Hier sind einige typische Szenarien.

Ausgehender Anruf:

INITIAL - Anrufer SIP-Endpunkt
ACCEPTED - Anrufer SIP-Endpunkt
RINGING - gewählte Nummer klingelt
CONNECTED - Verbindung mit gewählter nummer hergestellt
HANGUP - Anruf beendet

Eingehender Anruf:

RINGING - Benutzertelefon klingelt aufgrund eines eingehenden Anrufs
CONNECTED - Eingehender Anruf hergestellt
HANGUP - Anruf beendet

Event Struktur¶

Es gibt zwei Typen von Events:

activity Events: LOOGED_IN, LOGGED_OUT, READY, INFO, ERROR;
call Events: INITIAL, ACCEPTED, RINGING, CONNECTED, ON_HOLD, HANGUP, CANCEL;

Jedes activity -Event, das von Connector gesendet wird, enthält zwei Attribute:

name - Event Name;
message - Nachricht mit Event-Beschreibung / Grund;

Beispiel von Events:

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

Jedes "call" -Ereignis enthält auch zwei Attribute:

name - Event Name;
call -Anruf-Details wie unten beschrieben;

{
    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
    }
}

Verfügbare Anruf-Status (wie bei Anruf-Events):

INITIAL - wenn das Softphone Anrufer klingelt - tritt nur bei ausgehenden Anrufen auf;
ACCEPTED - wenn das Softphone Anrufer den Anruf annimmt (den Hörer abhebt) - tritt nur bei ausgehenden Anrufen auf;
RINGING - wenn Angerufener klingelt;
CONNECTED - wenn Angerufener den Anruf annimmt (den Hörer abhebt)
ON_HOLD - wenn Anrufer oder Angerufener den Anruf unterbricht;
HANGUP - wenn der Anrufer oder der Angerufener den Anruf beendet;

Verfügbare Anruf-Ziele:

OUTBOUND - für ausgehende Anrufe;
INBOUND - für eingehende Anrufe;

Connector API¶

Connector bietet API:

login - wird zum Authentifizieren des Benutzers in der Anwendung VoIPstudio und zum Herstellen einer neuen Verbindung mit dem SIP-Server verwendet
logout - wird zum Abmelden und Schließen der Verbindung verwendet
isConnected - wird verwendet, um anzuzeigen, ob der Benutzer bereits authentifiziert und mit VoIPstudio verbunden ist.
answer - wird verwendet, um eingehende Anrufe im Klingelzustand anzunehmen. Hinweis: Diese Methode funktioniert nur mit VoIPstudio Desktop Softphone min. v. 3.0.50
call - wird verwendet, um eine neue Verbindung mit der Zielnummer herzustellen
terminate - wird zum Beenden eines bestimmten Anrufs verwendet
transfer - Dient zum Weiterleiten eines bestimmten Anrufs an eine andere Telefonnummer oder Nebenstelle / Durchwahl
subscribe - ermöglicht die Erstellung von Abonnements zum Empfang von Call Events für andere Objekte als den angemeldeten Benutzer.

Alle diese Methoden wurden im Folgenden beschrieben.

Connector erstellen¶

Um eine Connector-Instanz zu erstellen, müssen wir die Konfigurationsoption einrichten und an den Konstruktor übergeben:

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

Nachdem Sie den Connector eingerichtet haben, können Sie die API des Connectors verwenden.

Erforderliche Parameter:

username - E-Mail-Adresse, die bei der Registrierung für voipstudio.de angegeben wurde
password - Benutzer-Passwort

oder:

apip_key - REST API Schlüssel, der dem Benutzerkonto zugewiesen ist;

Um zu überprüfen, ob der Benutzer bereits authentifiziert und der Connector bereits verbunden ist, sollten wir die Methode "isConnected" aufrufen.

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

Falls der Benutzer noch nicht verbunden ist, müssen Sie sich zunächst bei PRODUCT_NAME% anmelden:

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

oder:

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

Nach dem Anmeldeversuch werden folgende Ereignisse von Connector gesendet:

LOGGED_IN - nach erfolgreicher Authentifizierung;
READY - sobald die Verbindung zum SIP-Server hergestellt wird;
ERROR - wenn ein Fehler auftritt;

twoFactorAuth¶

Erforderliche Parameter:

authCode - gültiger Zwei-Faktor-Authentifizierungscode
nonce - Nonce-String, der vom vorherigen Aufruf der Methode login zurückgegeben wurde

Nach dem Authentifizierungsversuch werden die folgenden Ereignisse von Connector gesendet:

LOGGED_IN - nach erfolgreicher Authentifizierung;
READY - sobald die Verbindung mit dem SIP-Server hergestellt ist;
ERROR - wenn ein Fehler auftritt;

Logout¶

Wenn der Benutzer authentifiziert und verbunden ist, können wir ihn mit der Abmeldemethode ausloggen:

connector.logout();

Danach werden die folgenden Events per Connector gesendet:

LOGGED_OUT - nach erfolgreicher Abmeldung;
ERROR - wenn ein Fehler auftritt;

Call (Anrufe)¶

Erforderliche Parameter:

destination - Zielrufnummer in E164 format oder interne Durchwahl ohne Sonderzeichen;

Um einen Anruf zu tätigen, sollte die Call -Methode mit dem Zielparameter aufgerufen werden:

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

Danach werden folgende Ereignisse von Connector gesendet:

INITIAL - wenn der SIP-Endpunkt des Anrufers klingelt - tritt nur bei ausgehenden Anrufen auf;
ACCEPTED - wenn der SIP-Endpunkt des Anrufers den Anruf annimmt (nimmt den Hörer ab) - tritt nur bei ausgehenden Anrufen auf;
RINGING - um die App darüber zu informieren, dass ein OUTBOUND-Anruf hergestellt wird. Während eines OUTBOUND-Anrufs wird das RINGING-Event gesendet, nachdem das Softphone vom Anrufer den Anruf angenommen hat.
CONNECTED - wenn Angerufene den Anruf annimmt (beantwortet);
INFO - wenn die Aktion nicht ausgeführt werden kann;
ERROR - wenn ein Fehler auftritt;

terminate / Abbrechen¶

Erforderliche Parameter:

callId - einmalige Anruf-ID, die mit RINGING / CONNECTED-Events empfangen wurde; Diese ID sollte gespeichert werden, um zukünftige Anrufänderungen zu identifizieren.

Um einen bestimmten Aufruf zu beenden, sollte die Methode terminate mit dem Parameter callId aufgerufen werden:

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

Danach werden folgende Ereignisse von Connector gesendet:

HANGUP - nach erfolgreicher Anrufbeendigung;
INFO - wenn die Aktion nicht ausgeführt werden kann;
ERROR - wenn ein Fehler auftritt;

transfer / Weiterleitung¶

Erforderliche Parameter:

callId - einmalige Anruf-ID, die mit RINGING / CONNECTED-Events empfangen wurde; Diese ID sollte gespeichert werden, um zukünftige Anrufänderungen zu identifizieren;
destination - Zieltelefonnummer im Format E164 oder interne Nebenstelle ohne Sonderzeichen;

Um einen bestimmten Anruf an eine andere Telefonnummer oder Nebenstelle weiterzuleiten, sollte die Weiterleitungs-Methode mit der CallId und den Zielparametern aufgerufen werden:

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

Danach werden die folgenden Events per Connector gesendet:

HANGUP - nach erfolgreicher Anrufweiterleitung;
INFO - wenn die Aktion nicht ausgeführt werden kann;
ERROR - wenn ein Fehler auftritt;

Erforderliche Parameter:

node - String im Format node_type:node_id, der das Objekt beschreibt, für das wir Call Events abonnieren wollen.

Gültige node_type Werte sind:

* `user`
* `ivr`
* `Queue`
* `conf`

Zum Beispiel, um Call Events der Benutzer-ID 12345 zu abonnieren:

connector.subscribe('user:12345');

Nach erfolgreicher Anmeldung werden die folgenden Ereignisse von Connector gesendet:

SUBSCRIBED - nach erfolgreicher Anmeldung;
ERROR - wenn ein Fehler auftritt;

getSubscriptionURIs¶

Liefert ein Array aktiver URIs für Anrufereignis-Abonnements, zum Beispiel:

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

Beispiel-Implementierung - Cti.Platform¶

Zum besseren Verständnis haben wir eine Beispielimplementierung erstellt, die Cti.Connector verwendet, um eine Click to Call -Benutzeroberfläche zu erstellen und Ihnen zu zeigen, wie einfach sie zu integrieren ist. Der Beispielcode befindet sich im Repository CTI Connector.

Figure 57.2 VoIPstudio Connector example integration.

Das obige Bild zeigt fünf Schritte:

Plattform bereit: Connector und andere JavaScript-Dateien wurden erfolgreich geladen. Der Benutzer ist noch nicht authentifiziert. Der erste Schritt besteht darin, eine Verbindung zur App VoIPstudio über Cti.Connector herzustellen. Hierfür müssen Sie eine gültige E-Mail-Adresse und ein gültiges Kennwort von Ihrem VoIPstudio Konto angeben. Die Eingabe ungültiger Daten löst ein FEHLER-Event mit der richtigen Meldung aus.
Der Konnektor ist jetzt BEREIT: Nach erfolgreicher Authentifizierung haben wir das Event LOGGED_IN erhalten. Später, nachdem die Verbindung hergestellt wurde, hat der Konnektor das Event BEREIT gesendet. Jetzt können wir ausgehende Anrufe tätigen und eingehende Anrufe entgegennehmen;
Ausgehenden Anruf tätigen: Nachdem Sie die Telefonnummer eingegeben und auf die Schaltfläche Ausgehender Anruf geklickt haben, hat Connector das Event INITIAL gesendet. Dies bedeutet, dass das Softphone des Anrufers jetzt klingelt und auf die Annahme eines Anrufs wartet. Dies tritt nur bei Ausgehenden-Anrufen auf;
Nach dem Annehmen des Anrufs durch den Anrufer (der den Hörer abhebt) sendet der Connector das Event ACCEPTED. Jetzt kann der Klingelvorgang beginnen. Wenn Angerufener den Anruf nicht annehmen konnte, besetzt oder nicht erreichbar war, sendet Connector das Event CANCEL mit der richtigen Eigenschaft cause. Dies tritt nur bei AUSGEHENDEN-Anrufen auf;
Der Connector hat das Event RINGING gesendet, um unsere App zu benachrichtigen, dass versucht, eine neue Verbindung herzustellen. Das Telefon des Angerufenen klingelt jetzt; wenn die Verbindung nicht hergestellt werden konnte, wird das Event ERROR mit der richtigen Meldung zurückgegeben.
Empfangen eines eingehenden Anrufs: Wenn die Verbindung hergestellt wird, sendet der Konnektor ein RINGING-Ereignis mit Anruferinformationen. Diese Informationen können zum Beispiel dazu verwendet werden, den Anrufer zu identifizieren, die Anrufliste zu öffnen oder Details zum Anrufer anzuzeigen.
Konnektor ist jetzt VERBUNDEN: Wenn Angerufene unseren Ausgehenden-Anruf entgegennimmt oder nachdem der Eingehende-Anruf beantwortet wurde, sendet der Konnektor das Event VERBUNDEN, was bedeutet, dass der Anruf hergestellt wurde. Wenn ein Anruf aktiv ist, können wir ihn beenden oder an eine andere Telefonnummer weiterleiten. Nach Beendigung oder Weiterleitung kehren wir zu Schritt 1 zurück.

Wir empfehlen Ihnen, sich mit dieser Implementierung vertraut zu machen.

Wir haben es Cti.Platform genannt, da es den gesamten Code enthält, der zur Integration von Cti.Connector mit einer mit Bootstrap erstellten Beispiel-App erforderlich ist. Mit diesem Beispielcode können Sie sich bei VoIPstudio authentifizieren und Anrufe tätigen, weiterleiten und beenden. Diese Grundfunktionalität kann je nach Kundenwunsch einfach erweitert werden.

Integrationen - CTI-Anschluss¶

Anforderungen¶

Connector's Events¶

Typen von Events¶

Event Flow¶

Event Struktur¶

Connector API¶

Connector erstellen¶

Login¶

twoFactorAuth¶

Logout¶

Call (Anrufe)¶

terminate / Abbrechen¶

transfer / Weiterleitung¶

subscribe / abonnieren¶

getSubscriptionURIs¶

Beispiel-Implementierung - Cti.Platform¶