Anrufstatistiken in Grafana

• Was ist sipgate.io?
• Vorteile der Anrufstatistiken
• In diesem Tutorial
• Einblick in die Projekt-Architektur
• Aufsetzen des Projekts
• Ausführen des Projekts
• Custom Teams
• Ihre Umsetzungsmöglichkeiten
  • Call Events
  • Datenbank Schema
• Ein Überblick über das Grafana Dashboard
  • Vorhandene Bereiche
  • Filter-Optionen
• Fazit

Was ist sipgate.io?

SMS oder Faxe senden und empfangen, den Anrufverlauf abrufen,  Anrufe initiieren und manipulieren – das alles kann sipgate.io! Mit unseren APIs können Sie unsere Telekommunikationsfunktionen flexibel in Ihren Projekten integrieren. Unsere Library und Tutorials unterstützen Sie dabei, Ihre Telefonie möglichst bequem zu gestalten. 

Vorteile der Anrufstatistiken

Warum Sie eine sipgate-Grafana-Integration nutzen sollten  erfahren Sie auf unserer Website.

Die notwendigen Live-Daten für dieses Projekt können Sie mit unserer sipgate.io Node-Library abrufen.

In diesem Tutorial

Erfahren Sie in dieser Schritt-für-Schritt-Anleitung, wie Sie einen kleinen Server einrichten, die empfangenen Call-Events verarbeiten und diese in eine Datenbank schreiben können.

Mithilfe von Grafana erstellen Sie anhand Ihrer Datenbank ein personalisiertes Dashboard für Ihre Anrufstatistiken. Unter anderem können Sie folgende Fragen zu Ihrer Telefonie im Dashboard beantworten:

• Wie viele Kund:innen befinden sich momentan in der Warteschlange?
• Wie viele Anrufe sind derzeit aktiv?
• Wie lange müssen Kund:innen durchschnittlich warten?
• Wann werden Sie am häufigsten angerufen?
• Wie lange dauert ein durchschnittliches Telefonat?
• Wie viel Prozent der Anrufe werden auf die Voicemail umgeleitet?

Den Code für dieses Tutorial finden Sie in unserem GitHub.

Einblick in die Projekt-Architektur

Um einen besseren Überblick über die verschiedenen Komponenten dieses Projekts zu bekommen, werden folgende Bestandteile definiert:

• Call Statistics Service: ist das Herz des Projekts. Dieser Service empfängt und verarbeitet die Anrufinformationen von sipgate.io. Im Grunde ist der Service eine Schnittstelle zwischen sipgate.io und Grafana. Er basiert auf Node.js und nutzt die  sipgate.io Node Library für die Kommunikation mit sipgate. Weiterhin übernimmt dieser Service die Authentifizierung gegenüber der sipgate REST-API mittels  OAuth2.
• Database: Alle Anrufe, Gruppen und Teams werden hier gespeichert. In diesem Tutorial verwenden wir MariaDB von MySQL als Datenbank.
• Grafana: verwenden wir, um die Daten zu visualisieren.

Um eine konsistente und einfache Einrichtung sowohl in der Entwicklungs- als auch in der Produktionsumgebung zu gewährleisten, verwenden wir einen Docker-Container.

Aufsetzen des Projekts

Docker installieren

Um verschiedene Container für die Installation der Abhängigkeiten zu orchestrieren und einzurichten, sind Docker und Docker Compose erforderlich. Bitte folgen Sie den Anweisungen auf der Seite Get Docker & Install Docker Compose für Ihr System.

Danach ist Ihr System bereit, mehrere virtuelle Container als Multicontainer-Anwendung zu hosten.

Für Mac User: Öffnen Sie Ihre installierte Docker-Anwendung und überprüfen Sie, ob der Docker läuft.

Port-Forwarding

Wenn Sie Webhooks in Ihrer Live-Umgebung verwenden, sollten Sie Ihren Code auf einem geeigneten Webserver mit einer geeigneten Adresse ausführen. Für Entwicklungszwecke empfehlen wir jedoch die Nutzung eines Dienstes, der Ihre lokale Umgebung über das Internet zugänglich macht. Dies erleichtert erheblich das Testen Ihres geschriebenen Codes. Es gibt verschiedene kostenlose Dienste, die dafür genutzt werden können. Einige Beispiele sind localhost.run oder ngrok. Beide stellen Ihnen eine öffentliche URL zur Verfügung, mit der Sie Webhooks von sipgate.io empfangen können. Achten Sie darauf, dass Sie den richtigen Port weiterleiten (in diesem Tutorial Port 8080) und dass der von Ihnen gewählte Anbieter sichere Verbindungen über HTTPS bietet. Um das Grafana-Dashboard zugänglich zu machen, leiten Sie auch den Port 3009 weiter.

Datenbank einrichten

Die folgenden Informationen sind für die Einrichtung der MySQL-Datenbank erforderlich:

• MySQL-Host
• MySQL-Datenbank
• MySQL-Benutzer
• MySQL-Kennwort

Sie können die vorgegebenen Standardwerte verwenden sollten aber ein sicheres Passwort wählen.

Außerdem können Sie auch die Datenbank-Werte beliebig anpassen. Wenn Sie jedoch diese Werte ändern, müssen Sie das auch in der Datei .initdb.d/1_init_schema.sql aktualisieren.

Webhook, OAuth2 Client und Umgebungsvariablen

Für die Integration mit sipgate.io führen Sie folgende Schritte durch:

• Richten Sie einen OAuth2-Client ein, um den Anrufstatistik-Dienst zu autorisieren.
• Konfigurieren Sie die Webhook-URLs für Ereignisse in beide Richtungen.
• Definieren Sie einige erforderliche Umgebungsvariablen.

Um diese Schritte erfolgreich abzuschließen, gibt es folgende Möglichkeiten:

a) Setup-Dialog

Diese Option ist nur unter Verwendung von Linux- oder Mac-Systemen verfügbar. In dieser Variante führen Sie einen Setup-Dialog aus, der die zuvor genannten Schritte ausführt. Sie können das vollständige Skript unter setup.sh finden und wie folgt ausführen: 

./setup.sh

Folgende Informationen werden dafür gebraucht:

• Personal-Access-Token-ID und Personal-Access-Token
• Webhook-URL und -Port
• Interner Port

Ihr Personal-Access-Token wird nur beim Setup verwendet und nicht gespeichert, es kann danach auch ohne Probleme gelöscht werden. Um ein Personal-Access-Token zu erstellen, führen Sie folgende Schritte durch:

• Melden Sie sich auf app.sipgate.com mit Ihrem sipgate-Konto an.
• Gehen Sie hier auf „Meine Telefonie“ → „Benutzereinstellungen“ → „Personal-Access-Token verwalten“ → „Hinzufügen“.
• Geben Sie dem Token einen beliebigen Namen und bestätigen diesen mit „Weiter“.
• Wählen Sie hier die folgenden drei Scopes aus und bestätigen Sie Ihre Auswahl mit „Weiter“:
  1. authorization:oauth2:clients:read
  2. authorization:oauth2:clients:write
  3. settings:sipgateio:write
• Speichern Sie Ihre Token-ID und Ihren Token, um sich beim Setup-Skript authentifizieren zu können.

Für das Setup-Skript benötigen Sie ebenfalls die Webhook URL und den entsprechenden Port, die Sie aus den Schritten des Abschnittes Port-Forwarding bekommen haben.

Den internen Port müssen Sie in den meisten Fällen nicht ändern, bestätigen Sie hier einfach den vorgeschlagenen Wert 8080.

Die Werte für die Datenbank haben Sie bereits in Abschnitt Datenbank einrichten definiert.

b) Manuell

Diese alternative Option beschreibt, wie Sie die Schritte manuell ausführen können, wenn Sie sich mehr Überblick über Ihr Projekt wünschen, oder der Einrichtungsdialog nicht funktioniert.

1. Rufen Sie console.sipgate.com auf, und erstellen Sie einen neuen OAuth2-Client.

Fügen Sie dem OAuth2-Client die Redirect-URI und den Web Origin http://localhost:{WEBHOOK_PORT}/auth-code hinzu, um sich lokal authentifizieren zu können. Falls Sie sich auch extern authentifizieren wollen, können Sie {WEBHOOK_URL}/auth-code als Redirect-URI und Web Origin verwenden. Der Endpunkt /auth-code ist für die Verifizierung des Anrufstatistik-Dienstes via Auth-Token zuständig.

Anmerkung: Wenn Sie den Endpunkt /auth-code ändern, ändern Sie die definierte Konstante in der Datei call-statistics-service/src/AuthServer.ts AUTHENTICATION_CODE_ENDPOINT.

2. Benennen Sie die Datei .env.example in .env um:

      mv .env.example .env
   

3. Folgen Sie den Kommentaren in der .env-Datei, um die Umgebungsvariablen auszufüllen. Die Werte für diese Variablen haben Sie bereits in vorherigen Schritten konfiguriert.

Ausführen des Projekts

Nachdem Sie den Oauth2-Client und die Umgebungsvariablen eingerichtet haben, können Sie das Projekt auf folgende Weise ausführen:

make up

Nun navigieren Sie zu https://localhost:{WEBHOOK_PORT}/auth, um zunächst Ihr sipgate-Konto zu authentifizieren und REST-API-Calls durchführen zu können. Falls das Projekt entsprechend konfiguriert ist, verwenden Sie {WEBHOOK_URL}/auth, um sich auch extern authentifizieren zu können. Daraufhin werden Sie zum Login des Grafana-Dashboards weitergeleitet.

An dieser Stelle sollten Sie sich mit dem Standardkonto von Grafana user: admin, password: admin anmelden. Sie werden daraufhin aufgefordert, Ihr Passwort zu ändern. Nachdem Sie sich erfolgreich eingeloggt haben, werden Sie zum Grafana-Dashboard weitergeleitet.

Anmerkung: Grafana kann nur Statistiken für Ereignisse anzeigen, die gesammelt wurden, während der Anrufstatistik-Dienst lief. Wenn Sie eine neue Instanz des Dienstes einrichten, sind noch keine Ereignisse vorhanden. Daher kann Ihr Dashboard leer sein oder keine Daten anzeigen:

Das Projekt-Dashboard können Sie auch im Menü auf der linken Seite aufrufen. Folgen  Sie dem folgenden Pfad “Dashboards (Symbol mit vier Quadraten) → Manage → Call  Statistics”.

Für eine ausführlichere Beschreibung des Statistik-Dashboards lesen Sie das Kapitel Ein Überblick über das Grafana-Dashboard.

Custom Teams

Sie können Ihre Anrufstatistiken in Grafana nach benutzerdefinierten Gruppen und Ihren Teams filtern. Gruppen werden automatisch aus Ihrem sipgate-Konto übernommen. Wenn Sie benutzerdefinierte Teams hinzufügen möchten, können Sie dies tun, indem Sie die entsprechenden Rufnummern zu einem Team-Label in der teams.json folgendermaßen hinzufügen. Dabei muss ein Team mindestens zwei Rufnummern enthalten.

[
 {
   "name": "Sales Team for Product A",
   "numbers": ["+49211975379020", "+4921197537902"]
 }
]

Ihre Umsetzungsmöglichkeiten

Wie bereits erwähnt wurde, reagiert der Service auf Call-Events der sipgate.io Push-API. Diese Calls werden dann in die Datenbank geschrieben. Schließlich fragt Grafana diese Daten ab und visualisiert sie im Dashboard.

Call-Events

Es gibt drei Arten von call-events, die in der Statistik erfasst werden:

• NewCallEvent: übermittelt, dass ein neuer Anruf ankommt.
• AnswerEvents: wird ausgelöst, wenn der Anruf angenommen wird. 
• HangUpEvents: signalisiert, dass ein Anruf beendet wurde. 

Datenbank-Schema

Wenn die Datenbankinstanz zum ersten Mal initialisiert wird, wird das unten beschriebene Schema einmal ausgeführt. Es wird in .initdb.d/1_init_schema.sql gespeichert.

CREATE TABLE calls (
   call_id VARCHAR(255) PRIMARY KEY,
   start DATETIME NOT NULL,
   end DATETIME,
   answered_at DATETIME,
   direction ENUM('in','out') NOT NULL,
   mastersip_id VARCHAR(255),
   extension VARCHAR(255),
   caller_number VARCHAR(255) NOT NULL,
   callee_number VARCHAR(255) NOT NULL,
   answering_number VARCHAR(255),
   hangup_cause ENUM('normalClearing', 'busy', 'cancel', 'noAnswer', 'congestion', 'notFound', 'forwarded'),
   group_extension VARCHAR(255) NULL,
   voicemail BOOLEAN NOT NULL DEFAULT false,
   crashed BOOLEAN NOT NULL DEFAULT false
);

CREATE TABLE groups (
   extension VARCHAR(255) PRIMARY KEY,
   alias VARCHAR(255)
);

ALTER TABLE calls ADD FOREIGN KEY (group_extension) REFERENCES groups(extension) ON UPDATE CASCADE ON DELETE RESTRICT;

INSERT INTO groups VALUES('other', 'Other');

CREATE TABLE teams (
   id INTEGER PRIMARY KEY,
   name VARCHAR(255) NOT NULL
);

CREATE TABLE teams_numbers (
   team_id INTEGER NOT NULL,
   number VARCHAR(255) NOT NULL,
   FOREIGN KEY(team_id) REFERENCES teams(id)
);

INSERT INTO teams VALUES(0, 'Other');

CREATE TABLE authentication_params (
   token_type ENUM('access', 'refresh') PRIMARY KEY,
   token_value TEXT NOT NULL
);

public handleOnNewCall = async (
   newCallEvent: NewCallEvent
 ): Promise<void> => {
   console.log(`newCall from ${newCallEvent.from} to ${newCallEvent.to}`);

   if (this.isVoicemailCall(newCallEvent)) {
     await this.handleVoicemail(newCallEvent, new Date());
     return;
   }

   await this.handleRegularNewCall(newCallEvent, new Date());

   await this.insertCallIntoGroups(newCallEvent);
};

 public async handleOnAnswer(answerEvent: AnswerEvent) {
   console.log(`answer from ${answerEvent.from} to ${answerEvent.to}`);
   await this.updateAnswerDateAndNumber(answerEvent, new Date());
 }

private async updateAnswerDateAndNumber(
   answerEvent: AnswerEvent,
   date: Date
 ) {
   let callData = {
     answeredAt: date,
     answeringNumber: answerEvent.answeringNumber,
     crashed: false,
   };

   if (answerEvent.fullUserId) {
     const splitUserIdResult = splitFullUserId(answerEvent.fullUserId);
     callData["masterSipId"] = splitUserIdResult.masterSipId;
     callData["userExtension"] = splitUserIdResult.userExtension;
   }

   await this.database.updateCall(answerEvent.callId, callData);
 }

public async handleOnHangUp(hangUpEvent: HangUpEvent) {
   console.log(`hangup from ${hangUpEvent.from} to ${hangUpEvent.to}`);
   await this.updateEndDateOnCall(hangUpEvent, new Date());
}

 private async updateEndDateOnCall(hangupEvent: HangUpEvent, date: Date) {
   await this.database.updateCall(hangupEvent.callId, {
     end: date,
     hangupCause: hangupEvent.cause,
     crashed: false,
   });
}

private isVoicemailCall(newCallEvent: NewCallEvent) {
   return (
     newCallEvent.users?.length == 1 && newCallEvent.users[0] == "voicemail"
   );
}

private async handleVoicemail(newCallEvent: NewCallEvent, date: Date) {
 const origCallEvent = await this.database.getCall(
   newCallEvent.originalCallId
 );
 if (origCallEvent.length == 0) {
   await this.database.addCall(newCallEvent.callId, {
     start: date,
     direction: newCallEvent.direction,
     callerNumber: newCallEvent.from,
     calleeNumber: newCallEvent.to,
     voicemail: true,
   });
 } else {
   await this.database.updateCall(newCallEvent.originalCallId, {
     callId: newCallEvent.callId,
     voicemail: true,
   });
 }
}

public async crashCheck() {
 let queryString: string =
   "UPDATE calls SET crashed=true WHERE end IS NULL;";
 await this.query(queryString);
}

SELECT
 $__timeGroup(start, '$time_unit', 0) as time_sec,
 AVG(TIME_TO_SEC(TIMEDIFF(answered_at, start))) as "time in seconds"
FROM calls
GROUP BY time_sec

LEFT JOIN groups on calls.group_extension=groups.extension
LEFT JOIN teams_numbers on calls.callee_number=teams_numbers.number or calls.caller_number=teams_numbers.number
LEFT JOIN teams on teams_numbers.team_id=teams.id

WHERE (('${groups:pipe}' REGEXP groups.alias) OR ('${groups:pipe}' REGEXP "Other" AND calls.group_extension IS NULL))
AND   (('${teams:pipe}'  REGEXP teams.name) OR ('${teams:pipe}' REGEXP "Other"))

SELECT
 $__timeGroup(start, '$time_unit', 0) as time_sec,
 AVG(TIME_TO_SEC(TIMEDIFF(answered_at, start))) as "time in seconds"
FROM calls

LEFT JOIN groups on calls.group_extension=groups.extension
LEFT JOIN teams_numbers on calls.callee_number=teams_numbers.number or calls.caller_number=teams_numbers.number
LEFT JOIN teams on teams_numbers.team_id=teams.id

WHERE (('${groups:pipe}' REGEXP groups.alias) OR ('${groups:pipe}' REGEXP "Other" AND calls.group_extension IS NULL))
AND   (('${teams:pipe}'  REGEXP teams.name) OR ('${teams:pipe}' REGEXP "Other"))

GROUP BY time_sec

Ein Überblick über Grafana-Dashboard

Die gesamte Visualisierung der Statistiken erfolgt mit Grafana, das Sie unter http://localhost:3009 in Ihrem Browser aufrufen können. Melden Sie sich mit den Anmeldedaten an, die Sie festgelegt haben. Wenn Sie das Call-Statistics-Dashboard schon einmal aufgerufen haben, sollten Sie es im Abschnitt “Recently viewed dashboards” auf der Startseite verlinkt sehen können.

Andernfalls können Sie auf das Dashboard zugreifen, indem Sie dem folgenden Pfad im Menü auf der linken Seite folgen:  Dashboards (Symbol mit vier Quadraten) → Manage → General. Dort finden Sie einen Link zu Ihrem Dashboard.

Ihr Dashboard sollte ähnlich zu dem folgenden Screenshot aufgebaut sein:

Vorhandene Bereiche

In diesem Kapitel werden die einzelnen Bereiche des Anrufstatistik-Dashboards kurz beschrieben.

Die in jedem Bereich angezeigten Daten beziehen sich auf die Zeitspanne, die in der oberen, rechten Ecke definiert ist.

• Waiting in queue (In der Warteschlange): In diesem Bereich werden alle Anrufe angezeigt, die noch nicht angenommen oder aufgelegt wurden.
• Active calls (Aktuelle Anrufe): Aktuelle Anrufe werden in zwei separaten Feldern mit dem angegebenen Titel angezeigt. Das linke zeigt die Anzahl der Anrufe an, die angenommen und noch nicht aufgelegt wurden. Das rechte Feld zeigt weitere Details (die Startzeit, die Richtung und die Nummer des Besitzers)  zu jedem aktiven Anruf in einer Tabelle an. 
• Incoming and outgoing pick-up ratio (Verhältnis von ein- und ausgehenden Anrufen): In diesen Tortendiagrammen wird das Verhältnis zwischen angenommenen und nicht angenommenen Anrufen dargestellt. In der Legende wird jeweils die Gesamtzahl und die relative Anzahl der (nicht-)angenommenen Anrufe angegeben.
• Incoming and outcoming calls graph (Grafik der ein- und ausgehenden Anrufe): Diese Diagramme zeigen die unbeantworteten und beantworteten eingehenden und ausgehenden Anrufe.
• Mean call answer time (Durchschnittszeit bis zur Anrufannahme): In diesem Diagramm wird die durchschnittliche Zeit bis zur Annahme eines Anrufes dargestellt.
• Longest waiting times (Längste Wartezeiten): Hier werden die eingehenden Anrufe angezeigt, die die längste Wartezeit bis zur Annahme durch einen Mitarbeiter aufweisen.
• Average call duration (Durchschnittliche Gesprächsdauer): Hier wird die durchschnittliche Dauer aller ausgehenden und eingehenden Anrufe angezeigt.
• Longest calls (Längste Anrufe): In diesem Feld werden die Anfangszeit und die Dauer der zwanzig längsten Anrufe in absteigender Reihenfolge aufgeführt.
• Total calls (Gesamte Anrufe): Die Anzahl der gesamten Anrufe wird in diesem Bereich angezeigt.
• Total voicemail calls (Gesamte Voicemail-Anrufe): In diesem Diagramm werden alle Voicemail-Anrufe mit deren Uhrzeit angezeigt.
• Most calling numbers (Die häufigsten Rufnummern): Diese Tabelle zeigt die zwanzig Nummern, die Ihre Hotline am häufigsten anrufen, mit der jeweiligen Anzahl der Anrufe in absteigender Reihenfolge.

Filter-Optionen

Das Grafana-Dashboard bietet mehrere Filter-Optionen, um bestimmte Anrufstatistiken verwalten zu können. Sie können diese Filter aus jeder der folgenden Optionen frei kombinieren:

• Gruppen

Die Gruppen werden direkt aus Ihrem sipgate.io-Kontomportiert. Sie können nach Anrufen mit Teilnehmern aus einer bestimmten Gruppe oder einer Sammlung von Gruppen filtern.

• Teams

Die Teams definieren Sie selbst in der teams.json-Datei. Wie bei den Gruppen können Sie nach Gesprächen mit Teilnehmern aus einem bestimmten Team oder einer Sammlung von Teams filtern.

• Zeiteinheit

Je nach Zeiteinheit werden die Dashboard-Daten in Minuten, Stunden, Tagen oder jeder anderen Zeiteinheit zusammengefasst.

• Zeitspanne

Mit dieser Option können Sie die Zeitspanne für Ihre Anrufstatistiken beliebig definieren. Sie können zum Beispiel die Zeitspanne von einem Tag auf sieben Tage oder auch nur auf die letzte Stunde ändern.

Fazit

In diesem Tutorial haben Sie gelernt, wie Sie die Grafana-Dashboards für Ihr Unternehmen mit sipgate.io-Integration erstellen können, um Ihre Anrufstatistiken immer im Blick zu behalten.

Das vollständige Projekt finden Sie  in unserem GitHub- Repository.

Wenn Sie mehr über die Möglichkeiten unserer sipgate.io Node-Library erfahren möchten, schauen Sie sich unsere anderen Tutorials in unserem Blog an.