Sparkcentral CRM API

Mit der Sparkcentral CRM-Integration können Sie Kundenkontaktdaten aus CRMs oder anderen internen Geschäftsanwendungen in Sparkcentral abrufen. Um Ihr CRM in Sparkcentral zu integrieren, müssen Sie einen HTTPS-Endpunkt für Suchvorgänge bereitstellen. Sie können auch einen optionalen HTTPS-Endpunkt für die Bearbeitung von Rückschreibanfragen und einen HTTP-Endpunkt bereitstellen, mit dem Sparkcentral Benachrichtigungen von unserer Anwendung an Ihr CRM senden kann.

Lookup

Kontaktattribute erstellen

0. Erstellen Sie Kontaktattribute in Sparkcentral, gehen Sie zu Einstellungen, erweitern Sie den Arbeitsbereich für Agenten, wählen Sie Kontaktattribute aus, und wählen Sie dann Attribut hinzufügen aus).
2. Wählen Sie im Feld Attribut bearbeiten die Option Von CRM verwaltet aus. Das CRM wird die Quelle der Wahrheit für diese Attribute sein. Nachdem sie in Sparkcentral importiert wurden, ändern sie sich nur, wenn sich der Wert im CRM ändert.
3. Identifizieren Sie Lookup-Attribute, indem Sie Als Nachschlagattribut verwenden auswählen. Diese werden vom CRM verwendet, um die Daten eines Kunden zu finden. Wenn Sie beispielsweise einen Kunden per E-Mail-Adresse finden möchten, erstellen Sie ein Attribut namens „E-Mail“ und geben Sie es als Lookup an. Wenn die Anfrage von Sparkcentral an Ihr CRM gestellt wird, werden die Nachschlagefelder in den Anforderungstext aufgenommen.
4. Erstellen Sie einen Alias für das Attribut. Geben Sie im Feld Eindeutiger Identifikator einen Alias für das Lookup-Attribut ein. Dies wird verwendet, um die Antwort Ihres Systems dem Attribut zuzuordnen.

Integrations-URL konfigurieren

Um Daten von Ihrem CRM in Sparkcentral zu ziehen, müssen Sie einen POST-Endpunkt implementieren, der eine JSON-Anfrage akzeptiert und eine JSON-Antwort zurückgibt. Die Anfrage enthält die Lookup-Attribute, und die Antwort sollte die Kontaktdaten aus Ihrem CRM enthalten. Jede Anfrage enthält auch eine X-Sparkcentral-Signatur in ihren Headern. Auf diese Weise können Sie überprüfen, ob der Anruf von Sparkcentral stammt.

Nachdem dieser Endpunkt implementiert wurde, konfigurieren Sie ihn als Lookup-URL (gehen Sie zu Einstellungen, erweitern Sie Integrations-APIs, und wählen Sie dann CRM aus). Wenn die Lookup-URL konfiguriert wurde, erhalten Sie einen geheimen Schlüssel, mit dem Sie dieselbe Signatur wie in X-Sparkcentral-Signature berechnen können. Dadurch wird bestätigt, dass die Anfrage von Sparkcentral stammt.

Behandeln Sie die Anfrage

Wenn der Endpunkt in Ihrem System in Sparkcentral bereit und konfiguriert ist und ein oder mehrere Suchattribute identifiziert wurden, können Sie eine Anfrage über die Schaltfläche Suchen in der Konversationsansicht stellen. So würde die Anfrage aussehen:

curl -X POST https:///sparkcentral-lookup -H 'Inhaltstyp: anwendung/json' -H 'akzeptiere: Anwendung/json' -H 'X-Sparkcentral-Signatur: e6f93239a06e46ae9654fc9ad2fb4e1cc4eb213830a0d94e711570c047e43c57' 
-d '{"email":"fj@example.com"}'

Die Signatur wird mithilfe des HMAC-SHA256-Algorithmus mit dem gemeinsamen Geheimnis und dem Anforderungskörper generiert. Verwenden Sie Ihr Geheimnis, um die Signatur zu berechnen und mit der angegebenen Signatur zu vergleichen. Sowohl der geheime Schlüssel, den Sie erhalten haben, als auch die Signatur sind als Hexadezimalzeichenfolgen codiert. Stellen Sie sicher, dass Sie das gemeinsame Geheimnis von seiner hexadezimalen Darstellung in sein Binärformat konvertieren, bevor Sie es verwenden. Die meisten Sprachen werden mit vorbestellbaren Bibliotheken geliefert, um diese Signatur zu überprüfen. So sieht es beispielsweise in JavaScript aus:

const crypto = require ("crypto"); 
const SparkCentralSecret ="... "; //teile nicht! 
const ExpectedSignature = request.headers ["X-Sparkcentral-Signatur"]; 
const ActualSignature = crypto 
.createHMac ("sha256", Buffer.from (SparkCentralSecret," Hex")) 
.update (request.body," utf-8") 
.digest ("Hex "); 
wenn (ActualSignature! == ExpectedSignature){
throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
} 
console.log (json.parse (request.body) .email);

Nachdem Sie die Suche in Ihrem System durchgeführt haben, geben Sie Attribute als JSON-Antwort an Sparkcentral zurück. Die Schlüssel im Attribut-Objekt entsprechen den Aliasen, die zuvor in Sparkcentral hinzugefügt wurden. Wenn ein CRM Managed Attribut im Objekt fehlt oder der Schlüssel einen Nullwert hat, wird sein Wert in Sparkcentral gelöscht. Sparkcentral erwartet die Antwort in diesem Format:

Antwort 200 (Anwendung/JSON)

{
"AutoConfirm": false, 
"Attribute":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones",
"last_order_number": null
}
}

Bestätigen Sie Ihre Attribute

Die in der Antwort zurückgesendeten CRM-Attribute müssen bestätigt werden, bevor sie in Sparkcentral gespeichert werden. Es gibt zwei Möglichkeiten, dies zu tun:

• Klicken Sie auf die Schaltfläche Bestätigen, wenn die CRM-Attribute nach der Nachschlageanforderung in Sparkcentral angezeigt werden.
• Fügen Sie der Antwort ein AutoConfirm-Feld hinzu:

Antwort 200 (Anwendung/JSON)

{
"AutoConfirm": true, 
"attribute":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones"
}
}

Das Feld AutoConfirm weist Sparkcentral an, die Attribute automatisch zu speichern, ohne die Schaltfläche Bestätigen verwenden zu müssen.

Schreiben Sie zurück

Sie können benachrichtigt werden, wenn eine Konversation in Sparkcentral stattgefunden hat oder ein Agent eine aktuelle Konversation auf den Status „Ausstehend“ setzt. Auf diese Weise können Sie Konversationsdetails in Ihrem bestehenden CRM-System speichern. Weitere Anwendungsfälle umfassen das Auslösen von CSAT-Umfragen, die Fallerstellung und erweiterte Kundeneinblicke aus Social-Media-Profilen.

Schreibzu-URL konfigurieren

Um Daten von Sparkcentral in Ihr CRM zu übertragen, müssen Sie einen POST-Endpunkt implementieren, der eine JSON-Anfrage akzeptiert und eine JSON-Antwort zurückgibt. Die Anforderung enthält Rückschreiben-Nutzlast, und der Statuscode der Antwort stellt Ihre Fähigkeit dar, die Nutzlast zu analysieren und die Fähigkeit des CRM, die Daten aufzunehmen. Jede Anfrage enthält auch eine X-Sparkcentral-Signatur in ihren Headern. Auf diese Weise können Sie überprüfen, ob der Anruf von Sparkcentral stammt.

Konfigurieren Sie den Endpunkt als Write Back URL (gehen Sie zu Einstellungen, erweitern Sie &Integrations-APIs, und wählen Sie dann CRM aus). Wenn die Rückschreib-URL konfiguriert wurde, erhalten Sie einen geheimen Schlüssel, mit dem Sie dieselbe Signatur wie in X-Sparkcentral-Signature berechnen können. Dadurch wird bestätigt, dass die Anfrage von Sparkcentral stammt.

Behandeln Sie die Anfrage

Wenn der Endpunkt in Ihrem System in Sparkcentral bereit und konfiguriert ist und relevante Ereignisse in Sparkcentral auftreten, werden Anfragen an den konfigurierten Endpunkt gesendet. Alle dekodierten Write Back-Nutzlasten haben die folgenden Felder:

• type: Eine Zeichenfolge, die definiert, welche Art von Rückschreibanforderung verarbeitet wird. Wird verwendet, um die Struktur des Datenfeldes vorzuschlagen.
• version: Eine Nummer, die die Version des Anforderungstyps bezeichnet. Wird verwendet, um Änderungen an der Datenfeldstruktur zu markieren.
• iDemPotencyKey: Ein String, der jedes zurückzuschreibende Ereignis eindeutig identifiziert. Wird verwendet, um sicherzustellen, dass jede Anfrage nur einmal bearbeitet wird.
• data: Ein Objekt, das strukturierte Daten für den spezifischen Typ des Rückschreibens enthält. Ein Ereignis vom Typ CONVERSATION_RESOLVED hat beispielsweise Felder wie Medium, Kanal, Nachrichten*, Notizen , Themen, ContactProfile*, Attribute* und Agent unter anderem.

Die Anfrage enthält auch eine X-Sparkcentral-Signatur, die Sie auf die gleiche Weise wie bei Lookups überprüfen können.

* Gilt für alle Medien außer Twitter. Twitter-Handle, Tweets und Direktnachrichten-Transkripte sowie mittlere Kontaktattribute von Twitter (Twitter-Name, Anzahl der Follower usw.) werden nicht in der Nutzlast gesendet, um den Richtlinien zur Datennutzung von Twitter zu entsprechen.

Ereignisse CONVERSATION_RESOLVED und CONVERSATION_SET_TO_PENDING

Ereignisse mit einem Typ „CONVERSATION_RESOLVED“ oder „CONVERSATION_SET_TO_PENDING“ haben die folgende Datenstruktur:

{
"timestamp":" 2021-04-28T 09:43:26 .635984618Z", 
"idemPotencyKey ":" 6ebc6a78-d9e9-48be-b172-51eda40b7af8", 
"Version": 1, 
 "type":" CONVERSATION_RESOLVED", 
"Daten": {
"Konversation":{
      "id": "0ad42eef-a806-11eb-9642-f1ceb2f21def",
      "createdAt": "2021-04-28T09:42:27.004817183Z",
      "previousStatus": "new",
      "currentStatus": "resolved"
    }, 
"medium":{
      "id": "smooch-whatsapp"
    }, 
"kanal":{
      "id": "0-02534c5ac04-000-261ad914",
      "name": "channelname"
    }, 
"Agent":{
      "id": "11599",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@Hootsuite.com"
    }, 
 "contactProfile":{
      "id": "693ed54b-a426-11eb-9363-cffd945b4b2f",
      "mediumContactProfileId": "bb7b0f8f00cc989b97f0725b",
      "primaryIdentifier": "John Smith",
      "secondaryIdentifier": "+32439487192",
      "pictureUrl": null
    }, 
"statusUpdatedGrund": "5fd023f6-2e66-11eb-be07-092841b0717d - Antwort nicht erforderlich", 
"StatusUpdatedKommentar": "keine Frage", 
"StatusUpdateDat":" 2021-04-28T 09:43:26 .532948586Z ", 
"nachrichten": [
{
        "id": "0ad20c0d-a806-11eb-9642-f799d0e531de",
        "direction": "INBOUND",
        "text": "Figuur"
      }, 
{
        "id": "10664516-a806-11eb-9642-fbd9d431bd78",
        "direction": "OUTBOUND",
        "text": "dsghkjsdgmhlknsdmglhkjmsdlgkhjmsdgkljhlmdkgjh"
      }
], 
 "ContactTributes":  [
{
        "attribute": "smooch-whatsapp-profile-name",
        "value": "John Smith",
        "source": "MEDIUM"
      }, 
{
        "attribute": "smooch-whatsapp-phone-number",
        "value": "+32471263345",
        "source": "MEDIUM"
      }, 
{
        "attribute": "email",
        "value": "john.smith@Hootsuite.com",
        "source": "CRM_CONFIRMED"
      }, 
{
        "attribute": "first_name",
        "value": "John",
        "source": "CRM_CONFIRMED"
      }, 
{
        "attribute": "last_name",
        "value": "Smith",
        "source": "CRM_CONFIRMED"
      }, 
{
        "attribute": "company",
        "value": "Hootsuite",
        "source": "CRM_CONFIRMED"
      }, 
{
        "attribute": "spark-language",
        "value": "nl",
        "source": "CRM_CONFIRMED"
      }
], 
"notes": [], 
"Themen": []
}
}

Schreiben Sie zurück versuchen

Wenn die Rückschreibanforderung ein Timeout hat oder der Endpunkt einen Statuscode für nicht erfolgreich (2XX) zurückgibt, wird Sparkcentral es erneut mit exponentiellen Backoffs versuchen. Die Anfrage wird mit einer Verzögerung von 1, 2, 4, 8, 16 und 32 Stunden nach jeder Wiederholung (insgesamt 6 Anfragen) erneut gesendet, solange die Anfrage nicht erfolgreich ist. Wenn die Anfrage nach 6 Anfragen immer noch nicht erfolgreich war, speichern wir die Details zur fehlgeschlagenen Anfrage zur späteren Referenz. Wir empfehlen Ihnen, die Endpunktprotokolle regelmäßig zu überprüfen, um sicherzustellen, dass Rückschreibanforderungen beim ersten Mal ordnungsgemäß verarbeitet werden. Um zwischen eindeutigen Ereignissen zu unterscheiden, erhält jede Anfrage einen Idempotenzschlüssel.

Idempotenz-Key

Die Rückschreibanfragen von Sparkcentral verwenden einen Idempotency-Schlüssel, der es dem Rückschreibenendpunkt ermöglicht, sicherzustellen, dass er jede Anfrage einmal verarbeitet. Dieser Schlüssel hilft, wenn Anfragen während des Wiederholungszeitplans mehrmals gesendet werden, sodass der Endpunkt Anfragen idempotent bearbeiten kann. Der Schlüssel ist pro Anfrage eindeutig.

Benachrichtigung

Benachrichtigungs-URL konfigurieren

Wenn Sie Ihre CRM-verwalteten Kontaktattribute senden, überprüft Sparkcentral die Antwort. Um Validierungsfehler zu sehen, haben wir eine Möglichkeit bereitgestellt, Benachrichtigungen von Sparkcentral an Ihr System zu senden. Sie müssen einen POST-Endpunkt angeben, der einen JSON-Anforderungskörper akzeptiert. Konfigurieren Sie eine Benachrichtigungs-URL auf demselben Bildschirm, auf dem Sie eine Lookup-URL konfiguriert haben (gehen Sie zu Einstellungen, erweitern Sie &Integrations-APIs, und wählen Sie dann CRM aus).

Behandeln Sie die Anfrage

Wenn Validierungsfehler auftreten, sendet Sparkcentral eine Anfrage an die konfigurierte Benachrichtigungs-URL. Eine Anfrage sieht so aus:

{
"timestamp": "2019-01-30T15:49:10.630397Z",
"version": 1,
"eventType": "DATA_IMPORT_ERROR",
"messages": [
"testMessage1 key:testKey1 value:testValue1",
"testMessage2 key:testKey2 value:testValue2"
]
}

Verwenden Sie Ihr Geheimnis, um die X-Sparkcentral-Signatur auf die gleiche Weise zu überprüfen wie beim Nachschlagen und Rückschreiben. Die Anfrage enthält diese beiden Felder:

• EventType
• messages — ein Array expliziter Fehlermeldungen

Im Folgenden finden Sie die Ereignistypen, die von Sparkcentral gesendet werden können.

Die Antwort auf diese Anfrage kann 204 sein. Sparkcentral erwartet nichts im Reaktionstext.

Andere Aktionen

Aktualisieren

Die Schaltfläche Aktualisieren in der Konversationsansicht ruft verwaltete Attribute erneut aus dem CRM ab. Da diese Attribute zuvor bestätigt wurden, ist der Bestätigungsschritt nicht erforderlich.

Verknüpfung aufheben

Die Schaltfläche Verknüpfung aufheben in der Konversationsansicht entfernt CRM-verwaltete Attribute aus Sparkcentral.

Bestätigen

Die Schaltfläche Bestätigen speichert die zugehörigen validierten Informationen aus dem CRM in der Datenbank von Sparkcentral.

Klar

Die Schaltfläche Löschen setzt die Daten zurück, die vom Lookup-Endpunkt abgerufen wurden.