Artikel aktualisiert: 04. Februar 2022
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
- Gehen Sie in Sparkcentral zu Admin-Einstellungen, erweitern Sie Agentenarbeitsbereich, wählen Sie Kontaktattribute aus, und wählen Sie dann Attribut hinzufügen aus.
- 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.
- 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.
- 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:
Gehen Sie zu Admin-Einstellungen.
Erweitern Sie Integration und APIs.
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:
Gehen Sie zu Admin-Einstellungen.
Erweitern Sie Integration und APIs.
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 derDatenfeldstruktur
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 TypCONVERSATION_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:
Gehen Sie zu Admin-Einstellungen.
Erweitern Sie Integration und APIs.
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.
Event-Typ | Beschreibung |
---|---|
DATA_IMPORT_ERROR | Beim Abrufen von Daten aus dem CRM nach Sparkcentral ist ein Fehler aufgetreten. |
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.
Sie können nicht finden, was Sie suchen? Wir sind hier um zu helfen