Zum Inhalt

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.

cti-connector-diagram.png

Figure 10.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;
  • 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

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.

Login

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;

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;

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;

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;

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.

cti-connector-example-integration.png

Figure 10.2 VoIPstudio Connector example integration.

Das obige Bild zeigt fünf Schritte:

  1. 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.
  2. 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;
  3. 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;
  4. 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;
  5. 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.
  6. 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.
  7. 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.