Zum Hauptinhalt gehen

  Artikel aktualisiert: 10. November 2021

Sparkcentral Virtual Agent API

Die virtuellen Agenten von Sparkcentral ermöglichen es Unternehmen, der Plattform Bots hinzuzufügen, als wären sie echte Agenten. Sie können auf eingehende Nachrichten antworten, Konversationen lösen, Themen anwenden und Kontaktattribute festlegen. Anstatt die zu integrierenden Bot-Plattformen einzuschränken, wird eine generische API bereitgestellt, die Sie zur Integration in jede Plattform verwenden können.

Um Ihre bevorzugte Bot-Plattform in Sparkcentral zu integrieren, müssen Sie einen HTTPS-Endpunkt bereitstellen. Sparkcentral ruft diesen Endpunkt jedes Mal auf, wenn Ihrem virtuellen Agenten eine Konversation zugewiesen wird und wenn der Kontakt eine neue Nachricht sendet. Wenn Sie eine synchrone Bot-Plattform verwenden, können Sie diese Anfrage sofort mit der Antwort beantworten. Wenn Sie eine asynchrone Bot-Plattform verwenden, können Sie auch eine POST-Anfrage an Sparkcentral senden, um eine Antwort auf eine Konversation zu senden.

Zwei Arten von Virtual Agents

Inzeption

Ein virtueller Inception-Agent nimmt automatisch private Gespräche auf, die in den Kanälen beginnen, auf die er Zugriff hat. Wenn ein virtueller Inception-Agent einen menschlichen Agenten benötigt, platziert er die Konversation in die neue Warteschlange, damit jeder Agent antworten kann. Der Inception Virtual Agent kann auch eine Konversation lösen, wenn keine menschliche Hilfe erforderlich ist.

Da ein Virtual Inception Agent automatisch Gespräche in dem Kanal aufnimmt, auf den er Zugriff hat, können Sie nicht mehrere virtuelle Inception-Agents erstellen, die Zugriff auf denselben Kanal haben.

Delegation

Ein virtueller Agent der Delegation nimmt keine Gespräche automatisch auf. Stattdessen kann ein menschlicher Agent zu jedem Zeitpunkt des Gesprächs ein Gespräch mit einem virtuellen Vertreter der Delegation führen. Der virtuelle Agent der Delegation wird an dieser Stelle übernehmen. Die Übergaberegel legt fest, was passieren soll, wenn ein virtueller Delegationsagent einen menschlichen Agenten benötigt. Wenn „Neue Warteschlange“ ausgewählt ist, wechselt die Konversation in die neue Warteschlange, um von jedem Agenten abgeholt zu werden. Wenn „vorheriger Agent“ ausgewählt ist, weist der virtuelle Agent der Delegation die Konversation dem vorherigen menschlichen Agenten zu.

Mehrere virtuelle Delegationsagenten können Zugriff auf denselben Kanal haben. Ein menschlicher Agent muss gezielt den virtuellen Agenten auswählen, um die Konversation zu übernehmen.

Einen virtuellen Agent hinzufügen

So fügen Sie einen virtuellen Agent hinzu:

  1. Gehen Sie zu Einstellungen, erweitern Sie Virtual Agents, wählen Sie Benutzerdefinierte virtuelle Agenten aus, und wählen Sie dann Benutzerdefinierten virtuellen Agent hinzufügen aus.
  2. Geben Sie einen Namen für den virtuellen Agent ein. Dieser Name wird in Sparkcentral als „{Name}VA“ erscheinen.
  3. Geben Sie an, ob Ihr virtueller Agent als Inception-Agent oder Delegationsagent aktiviert werden soll.
  4. Die Webhook-URL muss angegeben werden, um Konversationsinformationen ordnungsgemäß an Ihren virtuellen Agenten zu senden (weitere Informationen finden Sie im Abschnitt Webhooks).
  5. Füllen Sie die restlichen Felder nach Belieben aus, einschließlich aller Übergaberegeln, die Sie hinzufügen möchten.
  6. Wählen Sie Speichernaus.
  7. Scrollen Sie nach unten zum Abschnitt Channel Access und wählen Sie mithilfe der Umschalter einen Kanal oder Kanäle aus, auf die auf diesen virtuellen Agent zugegriffen werden kann.

Timeout virtueller Agent

Sie können zwei Arten von Kontaktregeln für virtuelle Agents konfigurieren:

  • Timeout Virtual Agent - Bestimmt, wann eine Übergabe stattfindet, wenn der virtuelle Agent aus irgendeinem Grund nicht mehr reagiert. Das Maximum beträgt 60 Minuten.
  • Timeout-Kontakt - Bestimmt, wann eine Übergabe stattfindet, wenn der Kontakt (Benutzer) nicht mehr reagiert. Das Maximum beträgt 60 Minuten.

Umgang mit Fehlern

Wenn die Verbindung des virtuellen Agents ein Zeitabschluss hat, tritt ein Fehler auf, oder wenn der Kontakt ein Time-Out hat, können Sie Folgendes tun:

  • Markieren Sie die Konversation als Neu oder Gelöst
  • Wenden Sie ein Thema automatisch an
  • Wenn die Konversation als Gelöst gekennzeichnet ist, senden Sie dem Kunden automatisch eine Standardantwort

Einen virtuellen Agenten bearbeiten oder löschen

Um einen virtuellen Agenten zu bearbeiten, wählen Sie auf der Seite Benutzerdefinierte virtuelle Agents das Symbol Bearbeiten aus. Um einen virtuellen Agenten zu löschen, wählen Sie das Papierkorb-Symbol aus.

Zeigen Sie das Geheimnis für einen virtuellen Agenten an

Wählen Sie auf der Seite Benutzerdefinierter Virtual Agent das Symbol Bearbeiten neben dem virtuellen Agent aus. Sie können den für diesen virtuellen Agenten generierten gemeinsamen Secret auf der Seite Benutzerdefinierten virtuellen Agent bearbeiten anzeigen oder kopieren. Weitere Informationen finden Sie im Abschnitt Sichern von Webhooks.

Webhooks

Wenn dem virtuellen Agenten, den Sie im vorherigen Abschnitt registriert haben, eine Konversation zugewiesen wird, sendet Sparkcentral Ihnen ein Ereignis über die von Ihnen konfigurierte URL.

Es werden drei wichtige Ereignisse gesendet:

  • GESPRÄCH_STARTETE
  • GESPRÄCH_DELEGIERT
  • INBOUND_MESSAGE_EMPFANGENE

Gemeinsame Felder

Alle Ereignisse haben bestimmte gemeinsame Felder:

  • type: Eine Zeichenfolge, die definiert, welche Art von Ereignis aufgetreten ist (derzeit CONVERSATION_STARTED oder INBOUND_MESSAGE_RECED). In Zukunft können neue Ereignisse hinzugefügt werden. Vermeiden Sie es, mit einem Fehler auf unbekannte Werte zu reagieren, ignorieren Sie sie stattdessen. Abhängig von diesem Typ wird die Datenstruktur unterschiedlich sein.
  • version: Eine Nummer, die die Version des Anforderungstyps bezeichnet. Derzeit ist die Version immer 1. Versionen werden in Zukunft verwendet, um nicht abwärtskompatible Änderungen einzuführen.
  • idemPotencyKey: Eine Zeichenfolge, die jedes Ereignis eindeutig identifiziert. Wenn beim Senden des Ereignisses ein Timeout auftritt (oder wir erhalten eine Fehlerantwort), werden wir das Ereignis erneut versuchen. Dieser Schlüssel kann Ihnen helfen sicherzustellen, dass eine Anfrage nur einmal bearbeitet wird.
  • timestamp: Der Zeitstempel, als wir die Anfrage gesendet haben. Dies wird verwendet, um möglichen Wiederholungsangriffen entgegenzuwirken.
  • data: Ein Objekt, das strukturierte Daten für den bestimmten Typ enthält. Ein Ereignis vom Typ INBOUND_MESSAGE_RECEVED enthält beispielsweise Felder wie ConversationId und message. In Zukunft können Felder hinzugefügt werden.

GESPRÄCH_STARTETE

Das CONVERSATION_STARTED -Ereignis wird gesendet, wenn Ihrem virtuellen Inception Agent eine Konversation zugewiesen wird. Sie erhalten nur Nachrichten und können nur auf Nachrichten antworten, solange die Konversation dem virtuellen Inception Agent zugewiesen ist.

Im Rahmen dieser Veranstaltung erhalten Sie zusätzliche Informationen über das Kontaktprofil, das versucht, Sie zu kontaktieren, den Kanal, über den sie Sie kontaktieren, und die Kontaktattribute. Die Kontaktattribute umfassen mittelspezifische Informationen, zuvor manuell hinzugefügte Informationen und Informationen aus früheren CRM-Lookups. Beachten Sie, dass der Inception Virtual Agent das CONVERSATION_STARTED -Ereignis erhält, bevor eine konfigurierte CRM-Suche durchgeführt wird und das Ereignis daher keine neuen Informationen aus dem CRM enthält.

Nach dem CONVERSATION_STARTED -Ereignis erhalten Sie ab Beginn der Konversation für jede Nachricht, die der Kontakt sendet, ein INBOUND_MESSAGE_RECEVED Ereignis.

Kopieren
{
"idemPotencyKey":" 933d877e-a13f-4958-93a4-d5d4941bf624",
"Version ": 1,
"Typ":" CONVERSATION_STARTED",
"Zeitstempel":" 2019-01-17T 16:46:51 .908736Z",
"Daten ": {
"ConversationId":" 0-01d90bc1b13-000-9a9ca0d8",
"mittel":{ "id": "fb" },
"Kanal":{
"id": "0-019a0b43ad3-000-471aa28a",
"name": "Sparkcentral support channel"
},
"contactProfile":{
"id": "0-01835f0fec3-000-0a6c390a",
"mediumContactProfileId": "975734236828364800",
"primaryIdentifier": "jan_spark",
"secondaryIdentifier": "Jan Spark",
"pictureUrl": "http://image.com/sticky/default_profile_images/default_profile_normal.png"
},
"contactTributes": [
{ "attribute": "company", "value": "Sparkcentral", "source": "AGENT" },
{
"attribute": "fb-profile-image",
"value": "https://image.com/sticky/default_profile_images/default_profile_normal.png",
"source": "MEDIUM"
},
{
"attribute": "fb-verified",
"value": "Not Verified",
"source": "MEDIUM"
},
{
"attribute": "fb-account-created",
"value": "March 19, 2018",
"source": "MEDIUM"
},
{
"attribute": "fb-handle-name",
"value": "jan_spark",
"source": "MEDIUM"
},
{ "attribute": "fb-name", "value": "Jan Spark", "source": "MEDIUM" },
{
"attribute": "spark-url",
"value": "http://www.sparkcentral.com",
"source": "AGENT"
}
]
}
}

GESPRÄCH_DELEGIERT

Das CONVERSATION_DELEGATED -Ereignis wird gesendet, wenn Ihrem virtuellen Delegationsagenten eine Konversation zugewiesen wird. Wie das CONVERSATION_STARTED -Ereignis enthält dies zusätzliche Informationen über das Kontaktprofil, das versucht, Sie zu kontaktieren, den Kanal, über den sie Sie kontaktieren, und die Kontaktattribute.

Nach dem Ereignis CONVERSATION_DELEGATED erhalten Sie für jede Nachricht, die der Kontakt sendet, ein INBOUND_MESSAGE_RECEVED Ereignis, beginnend mit der Zuweisung der Konversation dem virtuellen Agenten. Im Gegensatz zum CONVERSATION_STARTED -Ereignis folgt dem CONVERSATION_DELEGATED -Ereignis oft nicht sofort ein INBOUND_MESSAGE_RECED. Stattdessen wird erwartet, dass der virtuelle Agent dem Kontakt die erste Frage stellt. Nachdem Sie ein CONVERSATION_DELEGATED Event erhalten haben, haben Sie 2 Minuten Zeit, um diese erste Frage zu stellen. Weitere Informationen finden Sie in den Anforderungen.

Kopieren
{
"timestamp":" 2019-03-28T 14:29:56 .727041Z",
"IdemPotencyKey ":" 8fa424c3-a88b-4f02-bd38-4e292a27597b",
"Version": 1,
"typ":" CONVERSATION_DELEGATED",
"Daten": {
"ConversationId":" 0-01f20ec5e10-000-860d4dde",
"mittel ":{ "id": "fb" },
"channel":{
"id": "0-01e25845518-000-19087686",
"name": "JansDevFbChannel4"
},
"contactProfile ":{
"id": "0-01f116a7f9c-000-b5d375aa",
"mediumContactProfileId": "cd067e88519aa063b15e9944",
"primaryIdentifier": "Anonymous",
"secondaryIdentifier": "Young Parrot",
"pictureUrl": null
},
"contactatTributes": [
{
"attribute": "fb-page-title",
"value": "In-Web Messaging Demo",
"source": "MEDIUM"
},
{
"attribute": "fb-page-url",
"value": "https://messenger-demoapp-dev/#JansDevSmoochChannel4",
"source": "MEDIUM"
},
{
"attribute": "fb-browser-language",
"value": "en-US",
"source": "MEDIUM"
},
{
"attribute": "fb-domain",
"value": "messenger-demoapp-dev",
"source": "MEDIUM"
},
{
"attribute": "fb-sdk-version",
"value": "1.14.2",
"source": "MEDIUM"
}
]
}
}

INBOUND_MESSAGE_EMPFANGENE

Nachdem die Konversation dem virtuellen Agenten zugewiesen wurde und nachdem Sie ein CONVERSATION_STARTED- oder ein CONVERSATION_DELEGATED -Ereignis erhalten haben, erhalten Sie INBOUND_MESSAGE_RECEVED Ereignisse. Diese Ereignisse treten jedes Mal auf, wenn der Kontakt eine Nachricht sendet. Beachten Sie, dass wir die Konversationsthemen mit jedem INBOUND_MESSAGE_RECEVED Ereignis senden.

Kopieren
{
"idemPotencyKey":" cc75552a-1a78-11e9-855e-6d1e71016abf",
"Version ": 1,
"Typ":" INBOUND_MESSAGE_RECEVED",
"Zeitstempel":" 2019-01-17T 16:56:16 .108626Z",
"Daten ": {
"ConversationId":" 0-01d90bc1b13-000-9a9ca0d8",
"Nachricht":{
"messageId": "cc75552a-1a78-11e9-855e-6d1e71016abf",
"text": "Hello"
},
"ConversationTopics": [" Thema1"," Thema2"]
}
}

ANTWORT

Ihre Antwort auf den Webhook sollte 200 OK sein. Im Text können Sie die Antwort zurückgeben, die Sie an den Kontakt senden möchten:

Kopieren
{
"sendMessage":{ "text": "Hi! How can I help you?", "attachment": "funny_cat.gif" },
"applyTopics": [" Hotelreservierung"],
"ApplyTags": ["Happy"],
"setContactatTributes":{ "account_number": "19758293529351" },
"vollständig":" ÜBERGABE"
}
  • sendMessage: (Optional) Die Nachricht, die Sie an den Kontakt senden möchten. Sie können nur Text, nur einen Anhang oder beides gleichzeitig senden. Wenn Sie einen Anhang senden möchten, müssen Sie ihn zuerst hochladen, daher empfehlen wir, den asynchronen Ablauf zu verwenden.
  • ApplyTopics: (Optional) Die Liste der Themen, die Sie auf die Konversation anwenden möchten (die Absicht oder Aktion, mit der Ihr Virtual Agent übereinstimmt). Themen, die in Sparkcentral nicht existieren, werden ignoriert.
  • ApplyTags: Die Liste der Tags, die Sie auf die Nachricht des Kontakts anwenden möchten. Tags, die in Sparkcentral nicht existieren, werden ignoriert. Es ist nur möglich, ApplyTags als Reaktion auf einen INBOUND_MESSAGE_RECEVED zu verwenden. Es ist auch möglich, eine bestimmte Nachricht durch Angabe der MessageID zu kennzeichnen. In diesem Fall können Sie mit" ApplyTags antworten": [{"messageId": "cc75552a-1a78-11e9-855e-6d1e71016abf", "tag": "Happy"}].
  • setContactatTributes: Die Attribute, die Sie für einen Kontakt festlegen möchten. Das Objekt ist eine Zuordnung zwischen dem Alias der Attributdefinition und dem festzulegenden Wert.
  • abgeschlossen. (Optional) Dies kann entweder ÜBERGABE sein, wenn Sie die Konversation einem anderen Agenten weitergeben möchten, oder RESOLVED, wenn Sie die Konversation lösen möchten. Wenn Sie ÜBERGABE bestehen, bestimmt die Übergaberegel, die Sie in den Einstellungen konfiguriert haben, was als nächstes passieren wird. Wenn die Übergaberegel „Niemand“ lautet, wird die Konversation ohne Eigentümer in die neue Warteschlange gestellt. Jeder menschliche Agent kann das Gespräch aufnehmen. Wenn die Regel auf „Vorheriger Agent“ festgelegt wurde, wird die Konversation dem vorherigen menschlichen Agenten zurückzugewiesen. Wenn es keinen vorherigen Agenten gab, wird die Konversation ohne Besitzer in die Warteschlange „Neu“ gestellt.

Wenn Sie sich in eine asynchrone Bot-Plattform integrieren, können Sie einfach einen leeren JSON-Körper {} zurückgeben und diese Nachricht mit einer POST-Anfrage senden. Wir empfehlen außerdem, die REST-API zu verwenden, wenn Sie einen Anhang senden möchten. Sie können mit {} antworten, einen Anhang mithilfe einer PST-Anfrage hochladen und den Anhang dann mithilfe einer POST-Anfrage senden.

Sichern von Webhooks

Beim Einrichten eines virtuellen Agenten erhielten Sie einen geheimen Schlüssel, mit dem Sie überprüfen können, ob eine eingehende Webhook-Anforderung wirklich ohne Änderungen von Sparkcentral stammt. In den Anforderungsheadern jedes Webhook-Aufrufs befindet sich die X-Sparkcentral-Signatur. Dies enthält eine HMAC-SHA256-Signatur, die auf dem Hauptteil der Anfrage basiert. Sowohl der geheime Schlüssel, den Sie erhalten haben, als auch die Signatur sind als Hexadezimalzeichenfolgen codiert. Die meisten Sprachen werden mit vorbestellbaren Bibliotheken geliefert, um diese Signatur zu überprüfen. Hier ist ein Beispielcode, um ihn in Node.js zu überprüfen:

Kopieren
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");
}
Hinweis: Vergewissern Sie sich, dass Sie die Signatur vom Körper so berechnen, wie sie ist, bevor Sie sie von JSON deserialisieren. Bei der Berechnung der Signatur wird der gesamte Leerraum als signifikant angesehen.
Als Teil des Anforderungstextes finden Sie einen Zeitstempel. Dies ist der Zeitpunkt, an dem eine Anfrage gesendet wurde. Um Wiederholungsangriffe zu verhindern, empfehlen wir zu überprüfen, ob dieser Zeitstempel nicht älter als 5 Minuten ist:
Kopieren
if (
moment (json.parse (request.body) .timestamp) .isBefore (
moment () .subtract (5," Minuten")
)
){
throw new createError.Unauthorized("Request too old");
}

Anforderungen

Um ein gutes Kundenerlebnis zu bieten, werden einige nicht funktionale Anforderungen an den Webhook gestellt. Wenn ein Webhook gesendet wird, haben Sie 10 Sekunden Zeit, um mit einem 200 OK zu antworten. Wenn ein Timeout auftritt, versuchen wir es dreimal mit einem exponentiellen Backoff (bis zu 2 Sekunden). Wenn die Fehler während der Wiederholungen weiterhin bestehen, wird die zugewiesene Konversation einem menschlichen Agenten übergeben, indem sie in die Warteschlange Neue gestellt wird.

Wenn der Kontakt eine Nachricht über Sparkcentral sendet, erwarten wir standardmäßig, dass der virtuelle Agent innerhalb von 5 Minuten auf diese Nachricht antwortet (indem er entweder die Antwort auf den Webhook-Aufruf oder die REST-API verwendet). Sie können das Timeout im Einstellungsbildschirm für Ihren virtuellen Agent (Timeout Virtual Agent) konfigurieren. Wenn der virtuelle Agent den Kontakt nicht beantwortet, wird die Konversation standardmäßig in die neue Warteschlange gestellt, damit ein menschlicher Agent abholen kann. Dies kann auch unter Einstellungen konfiguriert werden. Wenn Sie möchten, können Sie die Konversation automatisch auflösen und eine Nachricht an den Kontakt senden (z. B." Bitte versuchen Sie es in einer Weile erneut"). Der virtuelle Agent könnte auch entscheiden, die Kontrolle sofort zurückzugeben, indem er RESOLVED oder HANDOVER im vollständigen Feld sendet.

Ähnlich hat Ihr virtueller Agent nach einem CONVERSATION_DELEGATED-Ereignis standardmäßig 5 Minuten Zeit, um dem Kontakt eine Frage zu stellen. Wenn der virtuelle Agent dies nicht tut, wird die Konversation je nach Übergaberegel an den Vorbesitzer der Konversation zurückgegeben oder in die neue Warteschlange gestellt.

Autorisierung

Wenn Sie die Antworten asynchron senden oder die Konversation in Ihrem Fulfillment-Code manipulieren möchten, müssen Sie die REST-API für Virtual Agent aufrufen. Die Virtual Agent API verwendet den Ablauf für die Client-Berechtigung der Oauth 2.0-Spezifikation für die Clientauthentifizierung und -autorisierung.

Clients erhalten eine client_id und client_secret, um sich beim Autorisierungsserver von Sparkcentral zu authentifizieren, und ein access_token, das für API-Anforderungsautorisierung verwendet werden soll. Das access_token sollte in einem Autorisierungsheader verwendet werden, kann aber optional als Abfragezeichenfolgenparameter übergeben werden (siehe Anforderungs-/Antwortdetails in den folgenden Abschnitten). Wenn das access_token abläuft, gibt die API einen 401 nicht autorisierten zurück. Der Client kann dies automatisieren, indem er ein neues Zugriffstoken generiert und die fehlgeschlagene Anforderung mit dem neuen Zugriffstoken wiedergibt, wie im folgenden Abschnitt beschrieben. Dies ist dieselbe client_id und client_secret, die Sie möglicherweise für die Proactive Messaging-API oder die Realtime Reporting API erhalten haben.

Sparkcentral Benutzer mit Administratorrechten können API-Schlüssel in den Einstellungen generieren, indem sie &Integrations-APIs erweitern und Rest-API-Schlüssel auswählen.

Erteilung von Client-Anmel

Rufen Sie ein access_token ab, um autorisierte API-Anfragen zu stellen. Wenn das access_token abläuft, generieren Sie mit diesem Endpunkt ein neues Token.

ANFORDERN

Kopieren
$ curl -X POST https://public-api.sparkcentral.com/oauth2/token -H 'Inhaltstyp: application/x-www-form-urlencoded' -d& 'grant_type=client_credentials& Client_ID=Your_Client_ID_Here Client_Id_Here &scope=client-lesen'

OR

Kopieren
$ curl -X POST https://public-api-eu.sparkcentral.com/oauth2/token -H 'Inhaltstyp: application/x-www-form-urlencoded' -d& 'grant_type=client_credentials& Client_ID=Your_Client_ID_Here Client_Id_Here &scope=client-lesen'
  
API-Parameter
Parameter Status Beschreibung
grant_type erforderlich Muss auf client_credentials eingestellt sein
client_id erforderlich Sparkcentral hat die Kundenkennung angegeben
client_secret erforderlich Sparkcentral stellte Kundengeheimnis zur Verfügung
Geltungsbereich erforderlich Muss auf clientgelesen werden

ANTWORT

{ “token_type”: “bearer”, “access_token”: “a1b2c3d4e5f6”, “expires_in”: 43200 }

Response-Parameter und Beschreibungen
Parameter Beschreibung
token_type Der Tokentyp, der im Autorisierungsheader verwendet werden soll. Dies wird immer Träger für die Erteilung von Client-Anmeldeinformationen sein.
access_token Das Token, das zur Autorisierung von Anfragen verwendet wurde. Dies sollte den Anfragen als Autorisierungsheader hinzugefügt werden: Autorisierung: Inhaber a1b2c3d4e5f6. Die API akzeptiert auch access_token als Abfragezeichenfolgenparameter, jedoch ist die Verwendung des Autorisierungsheaders die bevorzugte Methode.
expires_in Die Anzahl der Sekunden bis zum Ablauf des Tokens (12 Stunden)

Die meisten Plattformen bieten sofort einsatzbereite Unterstützung für OAuth2. Zum Beispiel können Sie in Node.js mit dem axios-oauth-Client Folgendes tun:

Kopieren
const axios = require ('axios'); 
const oauth = require ('axios-oauth-client');
const TokenProvider = require ('axios-Token-Interceptor');
const restClient = axios.create ({ baseURL: 'https://public-api.sparkcentral.com' }); //oder public-api-eu.sparkcentral.com in EU
const getClientCredentials = oauth.client ( axios,{
url: 'https://public-api.sparkcentral.com/oauth2/token',
grant_type: 'client_credentials',
client_id: process.env.SPARKCENTRAL_CLIENT_ID,
client_secret: process.env.SPARKCENTRAL_CLIENT_SECRET,
scope: 'client-read'
});
RestClient.Interceptors.Request.Use (oauth.interceptor (TokenProvider, GetClientCredentials));

API für virtuelle Agenten

Gespräche

POST /virtual-agent/gesprächen/{conversationId}

Auf diese Weise können Sie die Konversation auf die gleiche Weise manipulieren, wie Sie es tun würden, wenn Sie auf eine Webhook-Anfrage antworten. Sie können eine Antwort senden, ein Thema hinzufügen und/oder die Konversation weitergeben. Jede Eigenschaft im Körper ist optional. Wenn Sie nur eine Nachricht senden möchten, können Sie {"sendMessage": {"text": "Hallo! "}}. Wenn Sie ein Thema anwenden und eine Nachricht vervollständigen, aber keine Nachricht senden möchten, können Sie beispielsweise senden {"applyTopics":["Spam"], "complete": "RESOLVED"}.

Beachten Sie, dass nur Themen, die genau zu einem Thema auf der Plattform passen, auf die Konversation angewendet werden (Groß- und Kleinschreibung wird nicht beachtet). Nicht vorhandene Themen werden ignoriert. Im Moment wird kein unscharfes Matching auftreten und typografische Fehler führen zu einem nicht existierenden Thema.

Gleiches gilt für Tags. Nur Tags, die genau mit einem Tag auf der Plattform übereinstimmen, werden auf eine bestimmte Nachricht angewendet (Groß- und Kleinschreibung wird nicht beachtet). Nicht vorhandene Tags werden ignoriert. Beachten Sie, dass es zwingend erforderlich ist, die MessageID anzugeben, wenn Sie die REST-API verwenden. Die MessageID ist Teil jedes INBOUND_MESSAGE_RECED-Ereignisses.

Wenn Sie einen Anhang senden möchten, müssen Sie den Anhang zuerst in einem separaten Aufruf hochladen (PUT /virtual-agent/conversations/{conversationId} /attachments/{filename}) und dann den Dateinamen verwenden, wenn Sie die message ({"sendMessage": {"Anlage":" "}}).

Wenn der Kontakt bereits einen Wert für die Attributdefinition mit einem bestimmten Alias gespeichert hat, wird das Update ignoriert. Wenn eine der Attributdefinitionen als CRM-Lookup-Werte konfiguriert ist, wird eine CRM-Lookup durchgeführt, nachdem die Attribute festgelegt wurden. Für die beste Leistung empfehlen wir, Kontaktattribute zusammen mit der Antwort festzulegen, um anzuzeigen, dass die Konversation abgeschlossen ist. Beachten Sie, dass der virtuelle Agent die neuen Attribute von der CRM-Antwort erst erhält, wenn das nächste CONVERSATION_STARTED- oder CONVERSATION_DELEGATED -Ereignis für ein Gespräch mit einem Kontakt empfangen wird.

Beispiel URI

POST /Virtual-Agent/Konversations/ConversationID

Anhänge

PUT /virtual-agent/gesprächen/{conversationId} /anhänge/{filename}

Auf diese Weise können Sie einen Anhang hochladen, den Sie in einer Konversation senden können. Sie müssen zuerst den Anhang hochladen und dann können Sie eine Nachricht mit Text und einem Anhang senden. Wenn Sie beispielsweise einen Anhang an /virtual-agent/conversations//attachments/cat.jpg hochladen, können Sie diesen Anhang senden, indem Sie {"sendMessage": {"text ":" Das ist eine Katze! "," Anhang":" cat.jpg"}} an /virtual-agent/gesprächs/. Der Dateiname sollte innerhalb einer Konversation eindeutig sein und ist für den Kontakt sichtbar, wenn er Ihren Anhang herunterlädt.

Der Content-Typ-Header sollte den richtigen Mime-Typ des Anhangs enthalten (z. B. „image/jpeg“). Der Header Content-Length sollte die Größe des Anhangs in Byte enthalten. Anhänge sollten weniger als 10 Megabyte betragen, um Fehler zu vermeiden.

 

Beispiel URI

PUT /Virtual-Agent/Konversations/ConversationId/Anhangments/Dateiname