Zum Hauptinhalt springen

TANSS Anrufimport und Telefonpopup

TANSS​

TANSS ist eine Service-Management- und ITSM-Lösung von HUCK IT für IT-Dienstleister und interne IT-Abteilungen. Für die Telefonieintegration sind insbesondere der Import von Anrufdaten sowie optionale Telefonpopups bei eingehenden oder ausgehenden Gesprächen relevant.

Die vorliegende Seite ist eine verkürzte Zusammenfassung der TANSS-EventBridge-Integration. Die ausführlichere Originalanleitung stammt von HUCK IT und ist hier zu finden: Starface EventBridge: Konfiguration für Anrufimport und Telefonpopup (TANSS). Vielen Dank an HUCK IT für die Konzeption und Bereitstellung der weiterführenden Integrationsdokumentation.

Anforderung​

Mit der EventBridge lassen sich STARFACE-Ereignisse an die TANSS-API übergeben. Dadurch können Gesprächsdaten automatisiert in TANSS importiert und zusätzlich optionale Telefonpopups im Browser ausgelöst werden.

Die nachfolgende Darstellung basiert inhaltlich auf der von HUCK IT veröffentlichten Integrationsdokumentation und wurde für diese Seite redaktionell verkürzt und an den Stil der EventBridge-Dokumentation angepasst.

Wichtige Informationen​

telephoneSystemId​

Dieser Parameter muss individuell angepasst werden. Jede Telefonanlage sollte in TANSS eine eigenständige ID erhalten.

Negative Werte dürfen nicht verwendet werden. Im folgenden Beispiel wird die telephoneSystemId 2 verwendet. Vor der Inbetriebnahme sollte geprüft werden, welche IDs in der TANSS-Datenbank bereits genutzt werden.

accountId​

Die accountId entspricht der ID, die in TANSS bei der Telefonanlagen-Benutzerzuordnung hinterlegt wird. Hinter dieser ID kann sich ein STARFACE-Benutzer oder eine STARFACE-Gruppe befinden.

API-Token​

Für die Telefonie-Schnittstelle in TANSS muss ein JSON Web Token erstellt und in den Event-Handlern als HTTP-Header verwendet werden.

TANSS-Version​

Der Import der Anrufdaten über die unten gezeigten Payloads setzt laut HUCK IT TANSS ab Version 10.13 voraus, da Parameter wie dateMillis, linkTimeMillis und endTimeMillis benötigt werden. Das Telefonpopup kann unabhängig davon bereits genutzt werden.

EventBridge Konfiguration​

Anrufimport nach TANSS​

Für den Import der Gesprächsdaten kann das Event de.starface.integration.uci.bo.events.NewCdrDataInfoEvent verwendet werden. Je nach Gesprächsrichtung und abhängig davon, ob callResultCausedBy gesetzt ist, werden vier Event-Handler verwendet.

Das Event​

Für den Import nach TANSS sind insbesondere folgende Felder relevant:

Relevante Event-Daten aus de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
{
  "accountId": "5603",
  "callerNumber": "+49712345678",
  "dialedNumber": "123",
  "cdrDataInfo": {
    "id": "171234",
    "startTime": 1768465815940,
    "linkTime": 1768465818123,
    "callResultTime": 1768465849000,
    "incoming": "true",
    "callResultCausedBy": "4508"
  },
  "callListEntry": {
    "answeredBy": "4508"
  }
}

Der passende Event-Handler​

Die HUCK-IT-Vorlage unterscheidet vier Fälle. Die URL ist jeweils https://meine.tanss.url/backend/api/calls/v1, die HTTP-Methode POST und die Header sind apiToken sowie Content-Type: application/json.

INCOMING​

  1. Event: de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
  2. Event-Daten/Extraktion:
    • id $.cdrDataInfo.id
    • startTime $.cdrDataInfo.startTime
    • linkTime $.cdrDataInfo.linkTime
    • callResultTime $.cdrDataInfo.callResultTime
    • accountId $.accountId
    • callerNumber $.callerNumber
    • dialedNumber $.dialedNumber
    • incoming $.cdrDataInfo.incoming
    • answeredBy $.callListEntry.answeredBy
    • callResultCausedBy $.cdrDataInfo.callResultCausedBy
  3. Bedingung: incoming == "true" && callResultCausedBy != "0"
  4. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
id
$.cdrDataInfo.id
startTime
$.cdrDataInfo.startTime
linkTime
$.cdrDataInfo.linkTime
callResultTime
$.cdrDataInfo.callResultTime
accountId
$.accountId
callerNumber
$.callerNumber
dialedNumber
$.dialedNumber
incoming
$.cdrDataInfo.incoming
answeredBy
$.callListEntry.answeredBy
callResultCausedBy
$.cdrDataInfo.callResultCausedBy
incoming == "true" && callResultCausedBy != "0"
{ "callId": "{{id}}", "dateMillis": {{startTime}}, "linkTimeMillis": {{linkTime}}, "endTimeMillis": {{callResultTime}}, "phoneParticipants": [ { "idString": "{{accountId}}" }, { "idString": "{{callResultCausedBy}}" }, { "idString": "{{answeredBy}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{dialedNumber}}", "direction": "INCOMING", "telephoneSystemId": "2" }

INCOMING ohne callResultCausedBy​

  1. Event: de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
  2. Bedingung: incoming == "true" && callResultCausedBy == "0"
  3. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
id
$.cdrDataInfo.id
startTime
$.cdrDataInfo.startTime
linkTime
$.cdrDataInfo.linkTime
callResultTime
$.cdrDataInfo.callResultTime
accountId
$.accountId
callerNumber
$.callerNumber
dialedNumber
$.dialedNumber
incoming
$.cdrDataInfo.incoming
answeredBy
$.callListEntry.answeredBy
callResultCausedBy
$.cdrDataInfo.callResultCausedBy
incoming == "true" && callResultCausedBy == "0"
{ "callId": "{{id}}", "dateMillis": {{startTime}}, "linkTimeMillis": {{linkTime}}, "endTimeMillis": {{callResultTime}}, "phoneParticipants": [ { "idString": "{{accountId}}" }, { "idString": "{{answeredBy}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{dialedNumber}}", "direction": "INCOMING", "telephoneSystemId": "2" }

OUTGOING​

  1. Event: de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
  2. Bedingung: incoming == "false" && callResultCausedBy != "0"
  3. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
id
$.cdrDataInfo.id
startTime
$.cdrDataInfo.startTime
linkTime
$.cdrDataInfo.linkTime
callResultTime
$.cdrDataInfo.callResultTime
accountId
$.accountId
callerNumber
$.callerNumber
dialedNumber
$.dialedNumber
incoming
$.cdrDataInfo.incoming
answeredBy
$.callListEntry.answeredBy
callResultCausedBy
$.cdrDataInfo.callResultCausedBy
incoming == "false" && callResultCausedBy != "0"
{ "callId": "{{id}}", "dateMillis": {{startTime}}, "linkTimeMillis": {{linkTime}}, "endTimeMillis": {{callResultTime}}, "phoneParticipants": [ { "idString": "{{accountId}}" }, { "idString": "{{callResultCausedBy}}" }, { "idString": "{{answeredBy}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{dialedNumber}}", "direction": "OUTGOING", "telephoneSystemId": "2" }

OUTGOING ohne callResultCausedBy​

  1. Event: de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
  2. Bedingung: incoming == "false" && callResultCausedBy == "0"
  3. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCdrDataInfoEvent
id
$.cdrDataInfo.id
startTime
$.cdrDataInfo.startTime
linkTime
$.cdrDataInfo.linkTime
callResultTime
$.cdrDataInfo.callResultTime
accountId
$.accountId
callerNumber
$.callerNumber
dialedNumber
$.dialedNumber
incoming
$.cdrDataInfo.incoming
answeredBy
$.callListEntry.answeredBy
callResultCausedBy
$.cdrDataInfo.callResultCausedBy
incoming == "false" && callResultCausedBy == "0"
{ "callId": "{{id}}", "dateMillis": {{startTime}}, "linkTimeMillis": {{linkTime}}, "endTimeMillis": {{callResultTime}}, "phoneParticipants": [ { "idString": "{{accountId}}" }, { "idString": "{{answeredBy}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{dialedNumber}}", "direction": "OUTGOING", "telephoneSystemId": "2" }

Telefonpopup in TANSS​

Für das optionale Telefonpopup kann das Event de.starface.integration.uci.bo.events.NewCallStateEvent verwendet werden. Hierfür werden drei Event-Handler verwendet: eingehend, ausgehend und optional das Schließen des Popups bei Gesprächsende.

Das Event​

Für das Popup sind vor allem Status, Zielrufnummer, Quellrufnummer und accountId relevant.

Relevante Event-Daten aus de.starface.integration.uci.bo.events.NewCallStateEvent
{
  "accountId": "5603",
  "call": {
    "state": "RINGING",
    "calledNumber": "123",
    "callerNumber": "+49712345678"
  }
}

Der passende Event-Handler​

Die URL ist für eingehende und ausgehende Popups jeweils https://meine.tanss.url/backend/api/calls/v1/notification. Für das automatische Schließen wird https://meine.tanss.url/backend/api/calls/v1/notification/close verwendet. Die HTTP-Methode ist jeweils POST, die Header sind apiToken sowie Content-Type: application/json.

Notification INCOMING​

  1. Event: de.starface.integration.uci.bo.events.NewCallStateEvent
  2. Event-Daten/Extraktion:
    • state $.call.state
    • accountId $.accountId
    • calledNumber $.call.calledNumber
    • callerNumber $.call.callerNumber
  3. Bedingung: state == "RINGING" && callerNumber != ""
  4. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCallStateEvent
state
$.call.state
accountId
$.accountId
calledNumber
$.call.calledNumber
callerNumber
$.call.callerNumber
state == "RINGING" && callerNumber != ""
{ "direction": "INCOMING", "phoneParticipants": [ { "idString": "{{accountId}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{calledNumber}}" }

Notification OUTGOING​

  1. Event: de.starface.integration.uci.bo.events.NewCallStateEvent
  2. Bedingung: state == "RINGBACK"
  3. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCallStateEvent
state
$.call.state
accountId
$.accountId
calledNumber
$.call.calledNumber
callerNumber
$.call.callerNumber
state == "RINGBACK"
{ "direction": "OUTGOING", "phoneParticipants": [ { "idString": "{{accountId}}" } ], "fromPhoneNumber": "{{callerNumber}}", "toPhoneNumber": "{{calledNumber}}" }

Notification HANGUP​

Dieser Handler ist optional und wird verwendet, wenn das TANSS-Telefonpopup nach Gesprächsende automatisch geschlossen werden soll.

  1. Event: de.starface.integration.uci.bo.events.NewCallStateEvent
  2. Event-Daten/Extraktion:
    • state $.call.state
    • accountId $.accountId
  3. Bedingung: state == "HANGUP"
  4. Aktion: Webhook aufrufen
de.starface.integration.uci.bo.events.NewCallStateEvent
state
$.call.state
accountId
$.accountId
state == "HANGUP"
{ "idString": "{{accountId}}" }

Hinweise​

  • Die hier gezeigten Beispiele sind bewusst verkürzt .
  • Die fachliche Grundlage der Konfiguration stammt von HUCK IT.
  • Die konkrete TANSS-URL, das API-Token sowie die produktive telephoneSystemId müssen individuell angepasst werden.
  • Für den vollständigen Einrichtungsprozess inklusive TANSS-seitiger Voraussetzungen empfiehlt sich die Originaldokumentation von HUCK IT.

Weiterführende Informationen​

Inhaltsverzeichnis