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 Lookups bereitstellen. Sie können auch einen optionalen HTTPS-Endpunkt für die Bearbeitung von Rückschreibanforderungen und einen HTTP-Endpunkt für Sparkcentral bereitstellen, um Benachrichtigungen von unserer Anwendung an Ihr CRM zu senden.

Sicherheit und Authentifizierung

Beim Senden oder Empfangen von Daten von Sparkcentral bieten wir zwei Authentifizierungsoptionen. Beide Mechanismen sind vorhanden, sodass Sie sicherstellen können, dass die Anfrage von Sparkcentral stammt.

Geteiltes Geheimnis

Wenn Sie den Shared Secret-Mechanismus wählen und eine URL konfigurieren, erhalten Sie ein Secret. Mit dem angegebenen Secret können Sie die Signatur berechnen, mit der Sie überprüfen können, ob der Anruf von Sparkcentral stammt. Mit diesem Mechanismus enthält jede einzelne Anfrage von Sparkcentral den X-Sparkcentral-Signatur-Header. Hier ist ein Beispiel für eine Anfrage:

curl -X POST https://sparkcentral-lookup -H 'Inhaltstyp: Anwendung/json' -H 'akzeptieren: 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 = benötigt ("Krypto"); 
const SparkCentralSecret ="... "; //nicht teilen! 
const ExpectedSignature = request.header ["X-Sparkcentral-Signatur"]; 
const ActualSignature = crypto 
.createHMac ("sha256 ", buffer.From (SparkCentral Secret," 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); 

OAuth

Wenn Ihre Endpoints OAuth2 unterstützen, können Sie Ihre Clientanmeldeinformationen, eine Token-URL und optional einen Scope in Sparkcentral konfigurieren.

Wir verwenden den Fluss OAuth2-Clientanmeldeinformationen, um uns gegen Ihr CRM zu authentifizieren. Die Token-URL ist der Endpunkt, an dem wir uns mit diesen Anmeldeinformationen authentifizieren und ein Zugriffstoken abrufen können. Um die eigentlichen Lookup-, Schreib- oder Benachrichtigungsanfragen durchzuführen, verwenden wir das Token im Authorization Header zur Authentifizierung.

Lookup

Kontaktattribute erstellen

0. Gehen Sie in Sparkcentral zu Admin-Einstellungen, erweitern Sie Agentenarbeitsbereich, 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 ist die Quelle der Wahrheit für diese Attribute. Nachdem sie in Sparkcentral importiert wurden, ändern sie sich nur, wenn sich der Wert im CRM ändert.
3. Identifizieren Sie Suchattribute, indem Sie Als Suchattribut verwenden auswählen. Diese werden vom CRM verwendet, um die Daten eines Kunden zu finden. Wenn Sie beispielsweise einen Kunden anhand einer E-Mail-Adresse suchen möchten, erstellen Sie ein Attribut mit dem Namen „E-Mail“ und legen Sie es als Suche fest. Wenn die Anfrage von Sparkcentral an Ihr CRM gesendet wird, sind die Suchfelder im Text der Anfrage enthalten.
4. Erstellen Sie einen Alias für das Attribut. Geben Sie im Feld Eindeutige Kennung einen Alias für das Suchattribut ein. Dies wird verwendet, um die Antwort von Ihrem System dem Attribut zuzuordnen.

Integrations-URL konfigurieren

Um Daten aus 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

Nachdem dieser Endpunkt implementiert wurde, konfigurieren Sie ihn als Suche-URL:

0. Gehen Sie zu Admin-Einstellungen.

2. Erweitern Sie Integration und APIs.

3. Wählen Sie CRM.

Behandeln Sie die Anfrage

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

Nachdem Sie die Suche in Ihrem System durchgeführt haben, übergeben Sie Attribute als JSON-Antwort an Sparkcentral zurück. Die Schlüssel im Attributs-Objekt entsprechen den Aliasnamen, die zuvor in Sparkcentral hinzugefügt wurden. Wenn ein CRM-verwaltetes 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 eine Rückschreibnutzlast, und der Statuscode der Antwort stellt Ihre Fähigkeit dar, die Nutzlast zu analysieren, und die Fähigkeit des CRM, die Daten aufzunehmen

Konfigurieren Sie den Endpunkt als Rückschreiben-URL:

0. Gehen Sie zu Admin-Einstellungen.

2. Erweitern Sie Integration und APIs.

3. Wählen Sie CRM.

Behandeln Sie die Anfrage

Wenn der Endpunkt in Ihrem System in Sparkcentral bereit und konfiguriert ist und relevante Ereignisse in Sparkcentral auftreten, werden Anforderungen an den konfigurierten Endpunkt gesendet. Alle dekodierten Rückschreibnutzdaten haben die folgenden Felder:

• type: Ein String, der 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 die spezifische Art des Rückschreibens enthält. Ein Ereignis vom Typ CONVERSATION_RESOLVED enthält beispielsweise Felder wie Medium, Kanal, Nachrichten*, Notizen, Themen, ContactProfile*, Attribute* und Agent.

* 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ückschreibeanforderung eine Zeitüberschreitung hat oder der Endpunkt einen nicht erfolgreichen Statuscode (2XX) zurückgibt, versucht Sparkcentral erneut mit exponentiellen Backoffs. Die Anforderung wird erneut mit einer Verzögerung von 1, 2, 4, 8, 16 und 32 Stunden nach jeder Wiederholung (insgesamt 6 Anfragen) gesendet, solange die Anforderung nicht erfolgreich ist. Wenn die Anfrage nach 6 Anfragen immer noch nicht erfolgreich war, speichern wir die Details der fehlgeschlagenen Anfrage zur späteren Bezugnahme. Wir empfehlen Ihnen, die Endpunktprotokolle regelmäßig zu überprüfen, um sicherzustellen, dass Rückschreibanforderungen beim ersten Mal ordnungsgemäß verarbeitet werden. Um zwischen einzelnen 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, führt Sparkcentral eine Validierung der Antwort durch. 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-Anforderungstext akzeptiert. Konfigurieren Sie eine Benachrichtigungs-URL auf demselben Bildschirm, auf dem Sie eine Suche-URL konfiguriert haben:

0. Gehen Sie zu Admin-Einstellungen.

2. Erweitern Sie Integration und APIs.

3. Wählen Sie CRM.

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"
]
}

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 Response-Body.

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.