Im Folgenden sollen einige Ausführungen und Darstellungen von CodeSnippets dazu dienen, Ihnen den Umgang mit unserer Schnittstelle zu erleichtern. Hierzu können Sie uns bei Fragen jederzeit kontaktieren. Gerne können wir auch die Implementierung eines Kampagnen-Skripts für Sie übernehmen. Nachfolgend sollen zunächst die verschiedenen Funktionen, welche Ihnen im Rahmen unserer Schnittstelle zur Verfügung stehen, erläutert werden. Abschließend erfolgt eine Beschreibung des Exports. Diese Beinhaltet verschiedene Formate, in welchen Sie die qualifizierten Lead-Informationen zurückerhalten können.
Nachfolgend sollen die Ihnen zur Verfügung stehenden Funktionen erläutert werden. Eine beipielhafte Umsetzung ist durch die eingefügten Code-Snippets ersichtlich. Dabei kann der Code jederzeit durch Sie kopiert und verwendet werden.
Diese Funktion ist dazu da, um Leads in das Sales_Q System zu senden und einen Chat zu beginnen.
URL | Methode | Content-Type |
---|---|---|
https://server.sales-q.com:8000/import | POST | application/json |
Pflicht Parameter im Body:
Parameter | Typ | Beschreibung |
---|---|---|
token | String | Enthält Ihren Sales_Q API Token. Er dient zur eindeutigen Identifizierung der Kampagne. |
leads | Object[] | Enthält mindestens einen Lead. |
leads[x].Phone | String | Enthält die Handynummer des Leads |
Dabei kann ein Lead beliebig viele Parameter haben. Diejenigen Datenpunkte,
die abgefragt werden sollen, werden automatisch aus dem Script hinzugefügt
und während des Prozesses befüllt.
Die Parameter müssen Parser-konform sein und dürfen keine Punkte oder
andere sonderbehandelten Zeichen enthalten.
Standardmäßig wird das zum Projektbeginn erstellte Campagnen-Script verwendet. Falls ein Lead nun ein eigenes/ individuelles script,bekommen soll, senden Sie dieses einfach als Parameter mit, wie unten im Beispiel aufgeführt. Im script kann dann auf die anderen Parameter des Leads zugegriffen werden.
Ein Element im optionalen/ individuellen script besteht aus:
Parameter | Typ | Beschreibung |
---|---|---|
content | String | Hier wird die Nachricht für den Baustein übergeben. |
state | String | Ist eindeutig (beginnt mit state: 1 und dieser ist Pflicht) und stellt die id des script Elements dar. |
next | Number, Object[] |
Ein Verweis auf den nächsten Baustein. |
dataconnect | String | Der Name der Variable, in die eine Antwort des Users gespeichert werden kann. |
type | String | Ist optional für Freitextfragen und beschreibt in welchem Format die Antwort im 'dataconnect' gespeichert werden soll. |
'type' kann eine der folgenden Parameter annehmen
Parameter | Regex | Beschreibung |
---|---|---|
Number | ^[0-9]+$ | Die Antwort muss eine Zahl sein |
Link | ^(http://www.|https://www.|http://|https://)?[a-z0-9]+([-.]{1}[a-z0-9]+)*.[a-z]{2,5}(:[0-9]{1,5})?(/.*)?$ | Die Antwort muss ein Link sein |
DateTime | ^s*(3[01]|[12][0-9]|0?[1-9]).(1[012]|0?[1-9]).((?:19|20)d{2})s* ([0-1]?[0-9]|2[0-3]):[0-5][0-9]$ | Die Antwort muss im Format 10.10.2020 15:30 angegeben werden |
Date | ^(0?[1-9]|[12][0-9]|3[01]).(0?[1-9]|1[012]).(19|20)([0-9][0-9])$ | Die Antwort muss im Format 10.10.2020 angegeben werden |
Diese Liste wird gerne auf Anfrage erweitert.
Es gibt 3 Arten von Nachrichten:
Type | next-Typ | dataconnect | Beschreibung |
---|---|---|---|
Einfache Nachricht |
Number | Bleibt leer | Es wird sofort die nächste Nachricht angestoßen. Das ist sehr praktisch, um es für den Leser übersichtlicher zu machen. |
Freitext- Frage |
Number | Enthält Variable |
Eine Freitextfrage wartet auf eine Antwort vom Endnutzer und schreibt diese in dataconnect. |
Multipe- Choice |
Object[] | Enthält Variable |
Eine Multiple-Choice Nachricht wartet auf eine vordefinierte Antwort und schreibt diese in dataconnect. |
Multiple-Choice: Wenn die Nachricht eine Multiple-Choice Frage ist, dann besteht der next-Parameter aus einem Array.
Für ein Object aus next in einer Multiple-Choice Frage:
Parameter | Typ | Beschreibung |
---|---|---|
answer | String | In answer steht die Antwort, die der Endnutzer eingeben kann. Unsere Systeme erkennen automatisch Variationen und Synonyme für diesen Begriff. |
next | String | In next steht beschrieben, welcher script-Baustein als nächstes gesendet werden soll. |
value | String, Boolean |
Ist optional und enthält den Wert, der in dataconnect geschrieben werden soll. Wenn kein value mitgegeben wird, wird die answer in dataconnect geschrieben. |
{ "token": "qf8ei4yHu2pzcaneFhdA...", "leads": [ { "Phone": "491788046563", "Anrede": "Herr", "Vorname": "Peter", "Nachname": "Müller" }, { "Phone": "49123456789", "Anrede": "Herr", "Vorname": "Johannes", "Nachname": "Muster", "Alter": "13e7a47d49f92e13e76183ad", "mappingId": "", "script": [ { "content": "{Anrede} {Nachname} ich kontaktiere Sie wegen... usw.", "state": "1", "next": "2" }, { "content": "Wann sollen wir Sie kontaktieren \nA) Morgens \nB) Mittags \nC) Abends", "state": "2", "next": [ { "answer": "A", "next": "3", "value": "Morgens" }, { "answer": "B", "next": "3", "value": "Mittags" }, { "answer": "C", "next": "4", "value": "Abends" } ], "dataconnect": "Wann kontaktieren" }, { "content": "Wann passt es Ihnen am besten", "state": "3", "next": "5", "dataconnect": "Uhrzeit", "type": "Number" }, { "content": "Das liegt leider außerhalb unserer Geschäftszeiten.", "state": "4", "next": "4" }, { "content": "Danke wir kontaktieren Sie dann im Laufe der Woche {Wann kontaktieren} um {Uhrzeit}", "state": "5", "next": "5" } ] } ] }
Erwartete Response:
Parameter | Typ | Beschreibung |
---|---|---|
response | Boolean | Beschreibt, ob die Anfrage erfolgreich war. |
log | String | Enthält weitere Informationen zur response. |
ids | Object[] | Enthält die Sales_Q-id sowie Phone der importierten Leads. Zusätzlich kann die Variable mappingId enthalten sein, wenn diese beim Import im Lead mitgegeben wurde. ids wird nur mitgesendet, wenn response true enthält. |
{ imported: true, log: "imported the leads", ids: [ { Phone: "491788046563", id: "5b929a13e7c7543ce399ea12" }, { Phone: "49123456789", id: "5b929a13e7c7543ce399ea13", mappingId: "13e7a47d49f92e13e76183ad" } ] }
Wenn Sales_Q den Qualifizierungsprozess für einen bestimmten Lead
beenden oder unterbrechen soll, entfernen Sie den Lead einfach aus unserem
System.
URL | Methode | Content-Type |
---|---|---|
https://server.sales-q.com:8000/remove | POST | application/json |
Pflicht Parameters im Body:
Parameter | Typ | Beschreibung |
---|---|---|
token | String | Enthält Ihren Sales_Q API Token. Er dient der eindeutigen Identifizierung der Kampagne. |
id | String | Enthält die ID eines Leads, die beim Import zurück gegeben wurde. |
Optionale Parameter:
Parameter | Typ | Beschreibung |
---|---|---|
message | String | Ermöglicht es dem Lead, noch vor dem Entfernen eine Nachricht zu schicken. |
{ token: "ed8779a2222dc578f2cffbf308411b41381a94ef25801", id: "5b929a13e7c7543ce399ea13" message: "hier die Schlussnachricht" }
Erwartete Response:
Parameter | Typ | Beschreibung |
---|---|---|
response | Boolean | Beschreibt, ob die Anfrage erfolgreich war. |
log | String | Enthält weitere Informationen zur response. |
obj | Object[] | Enthält den entfernten Lead mit allen bisher qualifizierten Datenpunkten. obj ist nicht vorhanden, wenn response false ist. |
{ response: true, log: "Object deleted", obj: { id: "5b929a13e7c7543ce399ea13", Phone: "491788046563", Anrede: "Herr", Vorname: "Peter", Nachname: "Müller", "Wann kontaktieren": "16 Uhr" } }
Um den aktuellen Stand der aktiven Leads zu erhalten.
GET | Methode | Content-Type |
---|---|---|
https://server.sales-q.com:8000/getAllLeads | POST | application/json |
Pflicht Header:
Header | Typ | Beschreibung |
---|---|---|
token | String | Enthält Ihren Sales_Q API Token. Er dient zur eindeutigen Identifizierung der Kampagne |
Erwartete Response:
Paraneter | Typ | Beschreibung |
---|---|---|
[leadid] | Object | Umfasst einen der Leads mit den Datenpunkten. |
[leadid].Status | String | Ein Element aus `Not contacted`, `Not on WhatsApp`, `Open`, `Engaged`, `Dead`, `Done` und `Archive` beschreibt, in welchem Status sich der Lead befindet. |
[leadid].state | Number | Enthält den state, in welchem der Lead sich im Script gerade befindet. |
[leadid].Comment | String | Enthält manchmal einen wichtigen Kommentar von einem Agent. |
[leadid].chathistory | Object[] | Enthält jegliche Konversation mit dem Lead. Analog zum Export. |
Als response folgt ein JSON-Objekt, welches die einzelnen Leads mit ihren Chatverläufen beinhaltet, wobei die IDs der Leads als Keys dienen.
{ "5b929a13e7c7543ce399ea13": { id: "5b929a13e7c7543ce399ea13", Phone: "491788046563", Anrede: "Herr", Vorname: "Peter", Nachname: "Müller", "Wann kontaktieren": "16 Uhr", Comment: "Möchte nicht vor 8 Uhr angerufen werden", Status: "Open", state: 2 chathistory: [ { timestamp: 1533908873, body: "Hallo Herr Müller", type: "chat", direction: "outgoing" }, { timestamp: 1533909099, body: "Hallo zurück", type: "chat", direction: "incoming" } ] }, ... hier nächster Lead }
Um den aktuellen Stand eines aktiven Leads zu erhalten.
URL | Methode | Content-Type |
---|---|---|
https://server.sales-q.com:8000/remove | POST | application/json |
Pflicht Header:
Header | Type | Beschreibung |
---|---|---|
token | String | Enthält Ihren Sales_Q API Token. Er dient der eindeutigen Identifizierung der Kampagne |
id | String | Enthält die ID des gewünschten Leads, welche beim Import erstellt wurde. |
Erwartete Response:
Parameter | Type | Beschreibung |
---|---|---|
lead | Object | Umfasst den angeforderten Lead mit allen Datenpunkten. |
lead.Status | String | Ein Element aus `Not contacted`, `Not on WhatsApp`, `Open`, `Engaged`, `Dead`, `Done` und `Archive` beschreibt, in welchem Status sich der Lead befindet. |
lead.state | Number | Enthält den state, in welchem der Lead sich im Script gerade befindet. |
lead.Comment | String | Enthält manchmal einen wichtigen Kommentar von einem Agenten. |
chathistory | Object[] | Enthält jegliche Konversation mit dem Lead. Analog zum Export. |
Wenn ein Lead durchqualifiziert wurde, wird er an einen Webhook zurückgespielt. Für den Export setzen wir zu Beginn der Kampagne einen Webhook. An diesen werden POST-Requsts mit den durchqualifizierten Leads gesendet.
URL | Methode | Content-Type |
---|---|---|
Sales_Q will call your URL | POST | application/json |
Request Prameter:
Parameter | Type | Beschreibung |
---|---|---|
token | String | Enthält Ihren Sales_Q API Token. Er dient zur eindeutigen Identifizierung der Kampagne. |
lead | Object[] | In lead befindet sich der qualifizierte Lead mit den Datenpunkten. |
chathistory | Object[] | Der gesamte Chatverlauf wird Ihnen mitgesendet und steht Ihnen im Nachgang zur Verfügung. |
chathistory[x].timestamp | Number | Enthält den Zeitpunkt, an dem die Nachricht gesendet/ empfangen wurde. Dieser ist als Unix Timestamp formatiert und kann dementspechend in alle Formate umgewandelt werden. |
chathistory[x].type | String | Enthält 'chat' für Textnachrichten oder den dazugehörigen MIME-Type für Medien. Oft verwendet sind 'image/jpeg' und 'audio/ogg; codecs=opus' |
chathistory[x].direction | String | Beschreibt, ob die Nachricht eingehend oder ausgehend ist. |
chathistory[x].body | String | Enthält die Nachricht für den Type 'chat'. Für Medien ist hier zu dem MIME-Type der Base64-String zu finden. |
Es werden diese zusätzlichen Datenpunkte mitgegeben:
Status: Ein Element aus `Not contacted`, `Not on WhatsApp`, `Open`, `Engaged`, `Dead`, `Done`, `Callback`und `Archive` beschreibt, in welchen Status sich der Lead befindet.
Name | Beschreibung |
---|---|
Not contacted | Lead wurde noch nicht angeschrieben. |
Not on WhatsApp | Lead hat keinen WhatsApp Account. |
Open | Die erste Nachricht ist angekommen. |
Engaged | Es gab vom Lead eine Antwort-Nachricht |
Dead | Lead hat kein Interesse mehr |
Done | Qualifizierungsprozess ist abgeschlossen. |
Callback | Lead hat nach der Qualifizierung oder der Löschung noch wichtige Infos geschickt. |
Archive | Lead hat nach der Qualifizierung oder der Löschung noch wichtige Infos geschickt. |
Comment: Enthält manchmal einen wichtigen Kommentar von einem unserer Agents.
state: Enthält den state in welchem der Lead sich im Script gerade befindet.
id: Enthält die id des Leads
{ token: "ed8779a2222dc578f2cffbf308411b41381a94ef25801", lead: { Phone: "491788046563", Anrede: "Herr", Vorname: "Peter", Nachname: "Müller", "Wann kontaktieren": "16 Uhr", Status: "Done" }, chathistory: [ { timestamp: 1533908873, body: "Hallo Herr Müller", type: "chat", direction: "outgoing", }, { timestamp: 1533909099, body: "Hallo zurück", type: "chat", direction: "incoming", } ] }