Terminologie
Der Begriff Client wird verwendet, um personenbezogene Kunden oder Partner zu identifizieren, die eine Integration mit dem personenbezogenen peoplefone CONNECTOR durchführen.
Der Begriff Telefonsuchdienst wird verwendet, um den Dienst des Clients zu identifizieren, der die aktuelle Schnittstelle für den peoplefone CONNECTOR zum Erfassen von Daten verfügbar macht.
Überblick
![](http://support.peoplefone.ch/wp-content/uploads/2020/06/1_connector_cti-rest-api.png)
Die peoplefone CONNECTOR API deckt mehrere Anwendungsfälle ab:
- Datensuche zu Benachrichtigungszwecken
Wenn ein Telefonanruf ausgeführt wird (eingehend oder ausgehend), benachrichtigt peoplefone HOSTED den peoplefone CONNECTOR, der mithilfe der in diesem Artikel beschriebenen REST API nach Daten sucht.
- Interaktion mit dem Business Workflow
Wenn der Benutzer von peoplefone CONNECTOR auf einen der Geschäftsabläufe klickt, überträgt der Benutzer von peoplefone CONNECTOR die Anforderung zur Behandlung an den Telefonsuchdienst. Der Geschäftsworkflow kann das Erstellen eines Tickets oder eines Anrufverlaufs im CRM umfassen.
Teil 1 – Datenabfrage
Anfrage
URL
https://clientServiceAddress/someController
Der Request-URL wird vom Client definiert, damit peoplefone CONNECTOR den Telefonsuchdienst erreichen kann. Diese URL enthält KEINE privaten Daten, die für die Suche erforderlich sind. Diese Daten werden über HTTP-Header bereitgestellt.
Parameter abfragen
peoplefone CONNECTOR gibt die Telefonnummer über den folgenden Abfrage-Parameter an:
Schlüssel: Telefonnummer
Wert (sample): 4178907228
https://clientServiceAddress/someController?PhoneNumber=4178907228
HTTP-Header
Zur Authentifizierung stellt peoplefone CONNECTOR einen Token über den folgenden HTTP-Header bereit:
Schüssel: X-Execution-Token
Wert: jlvlkdshvövdjhwgjwogjhwg
Body
Der Body der Anfrage wird vorerst nicht vom peoplefone CONNECTOR verwendet:
{
"inputs": {
"phoneNumber":"41215522000"
}
}
Antwort
Beispiel vom HTTP Body
[
{
"Name": "Alexa Holiday",
"Company": "White Cross Co",
"ContactUri": "https://...",
"CompanyUri": "https://...",
"Id": "Crm Identification Number",
"CrmName": "Sugar CRM",
"CrmLogo": "https://...",
"CustomData": {
"Title1": "Data1",
"Title2": "Data2"
}
},
{
...
}
]
Layer 1: Die Liste
Das erwartete Ergebnis ist ein Array von Objekten. Es wird empfohlen, nur eine sehr kleine Anzahl von Ergebnissen zurückzugeben. Der Wert von maximal 5 Ergebnissen eignet sich am besten für ein ausgewogenes Verhältnis zwischen Leistung und Präzision. Das Erhöhen dieses Werts kann jedoch in allen Phasen des Systems zu erheblichen Verzögerungen und Leistungsproblemen führen.
Wenn die Abfrage keinen Wert zurückgibt, wird von peoplefone CONNECTOR erwartet, dass sie ein leeres Array mit einem Statuscode von 200 erhält. In diesem Fall wird KEIN 404-Statuscode erwartet. Der 404-Statuscode bedeutet, dass auf den Telefonsuchdienst nicht zugegriffen werden kann.
Layer 2: Das Objekt
Die Objekte, aus denen die Liste besteht, stellen einen Eintrag dar, der für die angegebene Telefonnummer im integrierten CRM gefunden wurde. Dieses Objekt enthält nur wenige Felder, die für peoplefone CONNECTOR erforderlich sind, um den Eintrag ordnungsgemäss anzuzeigen, sowie eine Liste von Schlüssel-Wert-Paaren für bestimmte Daten, die unser Kunde hinzufügen möchte.
Feldname | Beschreibung |
Name | Der vollständige Name des gefundenen Kontakts. Dies wird in der Benutzeroberfläche verwendet, um den Namen des Kontakts anzuzeigen. |
Firma | Der Name der Firma, mit der der Kontakt verknüpft ist. Dies wird in der Benutzeroberfläche verwendet, um den Namen des Unternehmens anzuzeigen. |
ContactUri | Der URI für den Zugriff auf die Kontaktseite im CRM. Dies wird in der Benutzeroberfläche verwendet, um eine verbindung zum Kontakt herzustellen. |
CompanyUri | Der URI für den Zugriff auf die Unternehmensseite im CRM. Dies wird in der Benutzeroberfläche verwendet, um eine verbindung zum Unternehmen herzustellen. |
Id | Die ID des Kontakts im CRM. Dieser Wert wird nicht angezeigt.| |
CrmName | Der Name des CRM. Dieser Wert wird, insofern angegeben, verwendet, um einen Tooltip zum CRM-Logo hinzuzufügen. |
CrmLogo | Die URL des Logos des CRM. Dieser Wert wird, falls angegeben, verwendet, um ein Logo auf der Kontaktkarte für diesen Eintrag hinzuzufügen. Dies ist optional, wenn der Kunde nur ein CRM integriert. Es wird jedoch nützlich, wenn der Kunde mehrere CRM-Integrationen hat. |
CustomFields | Das Objekt CustomFields ist eine Reihe von Schlüssel-Wert-Paaren, mit denen der Kunde alle Daten übertragen kann, die er für die benötigt. |
Part 2 – Business workflow
Anfrage
URL
<root-url>/<workflow-name>
The <root-url> ist derselbe Wert wie bei der Suche (siehe Teil 1). Der ist der Name, der von der Suche im CrmActions-Array zurückgegeben wird.
The <workflow-name> ist relativ frei zu verwenden, jedoch wird der Wert an zwei anderen Stellen ausserhalb der peoplefone CONNECTOR API Definition verwendet:
- Zur Anzeige des Business-Workflows auf der peoplefone CONNECTOR Webseite. Für einige vordefinierte Werte wird er übersetzt, ansonsten wird er AS-IS angezeigt.
- Für die automatische Konfiguration von Geschäftsabläufen. Im Moment kann nur der Business-Workflow “CallFlow” im peoplefone CUSTOMER-PORTAL automatisch konfiguriert werden, alle anderen Fälle werden nur manuell eingestellt.
Abfrage-Parameter
peoplefone CONNECTOR liefert keine Abfrageparameter
HTTP Headers
Für die Authentifizierung liefert peoplefone CONNECTOR die gleichen Header wie für die Suche, wie auf der peoplefone CUSTOMER-PORTAL Seite konfiguriert.
Body
Der Hauptteil der Anfrage enthält alle erforderlichen Informationen für den auszuführenden Geschäftsablauf. Diese Nutzlast könnte in Zukunft noch erweitert werden. Es handelt sich um ein Feld “inputs”, das ein einfaches JSON-Objekt mit den folgenden Feldern enthält:
Field Name | Description |
contactCrmId | The ID of the contact in the CRM (as retrieved from the lookup) |
userCrmId | The ID of the user linked to the current SIP user (as configured in the CUSTOMER-PORTAL page) |
originatorNumber | The phone number that initiated the call. |
originatorName | When available the name of the person who initiated the call. |
destinationNumber | The phone number composed by the caller. |
destinationName | When available the name of the person which answer the call. |
direction | The direction of the call, either ‘incoming’ or ‘outgoing’. |
startedTime | The date/time when the call was started (ringing). |
answeredTime | The date/time when the call was answered, this value is empty if the call was not answered. |
endedTime | The date/time when the call was ended. |
declinedTime | The date/time when the call was aborted, this value is empty if the call was answered. |
id | The id returned by the CRM on the previous workflow request (for the same call), null in case it is the first request |
{
"inputs": {
"contactCrmId":"...",
"userCrmId":"...",
...
}
}
Antwort
Die von peoplefone CONNECTOR erwartete Antwort ist ein einfaches JSON-Objekt mit zwei Feldern, wobei die gesamte Antwort sowie die einzelnen Felder optional sind. Der Zweck der URL ist es, optional die CRM-Seite direkt nach Beendigung des Workflows zu öffnen.
Field Name | Description |
id | The ID of the object created by the business workflow |
url | The URL to access the object created by the business workflow |
{
"id":"...",
"url":"..."
}
Probleme mit der Leistung
Die Reaktionszeit ist entscheidend, damit der Benutzer so schnell wie möglich die richtigen Informationen in der peoplefone CONNECTOR-Anwendung sehen kann.
Der phone lookup service muss so schnell wie möglich sein, um eine kurze Antwortzeit für den Benutzer von peoplefone CONNECTOR zu gewährleisten. Sollte der phone lookup service dennoch zu langsam reagieren, sendet peoplefone CONNECTOR einen Timeout und antwortet mit einer Basisinformation für den Benutzer (Telefonnummer und Status des Anrufs mit dem Namen “unbekannt”.