Menu Schließen

peoplefone CONNECTOR API (REST API)

peoplefone

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

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.

FeldnameBeschreibung
NameDer vollständige Name des gefundenen Kontakts. Dies wird in der Benutzeroberfläche verwendet, um den Namen des Kontakts anzuzeigen.
FirmaDer Name der Firma, mit der der Kontakt verknüpft ist. Dies wird in der Benutzeroberfläche verwendet, um den Namen des Unternehmens anzuzeigen.
ContactUriDer URI für den Zugriff auf die Kontaktseite im CRM. Dies wird in der Benutzeroberfläche verwendet, um eine verbindung zum Kontakt herzustellen.
CompanyUriDer URI für den Zugriff auf die Unternehmensseite im CRM. Dies wird in der Benutzeroberfläche verwendet, um eine verbindung zum Unternehmen herzustellen.
IdDie ID des Kontakts im CRM. Dieser Wert wird nicht angezeigt.|
CrmNameDer Name des CRM. Dieser Wert wird, insofern angegeben, verwendet, um einen Tooltip zum CRM-Logo hinzuzufügen.
CrmLogoDie 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.
CustomFieldsDas 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 NameDescription
contactCrmIdThe ID of the contact in the CRM (as retrieved from the lookup)
userCrmIdThe ID of the user linked to the current SIP user (as configured in the CUSTOMER-PORTAL page)
originatorNumberThe phone number that initiated the call.
originatorNameWhen available the name of the person who initiated the call.
destinationNumberThe phone number composed by the caller.
destinationNameWhen available the name of the person which answer the call.
directionThe direction of the call, either ‘incoming’ or ‘outgoing’.
startedTimeThe date/time when the call was started (ringing).
answeredTimeThe date/time when the call was answered, this value is empty if the call was not answered.
endedTimeThe date/time when the call was ended.
declinedTimeThe date/time when the call was aborted, this value is empty if the call was answered.
idThe 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 NameDescription
idThe ID of the object created by the business workflow
urlThe 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».