Sales_Q

1. How to Use

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.

2. Funktionen

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.

2.1. Import

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.

Import example

{
  "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.

Import response

{
   imported: true,
   log: "imported the leads",
   ids: [
      {
         Phone: "491788046563",
         id: "5b929a13e7c7543ce399ea12"
      },
      {
         Phone: "49123456789",
         id: "5b929a13e7c7543ce399ea13",
         mappingId: "13e7a47d49f92e13e76183ad"
      }
   ]
}

2.2. Remove

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.

Remove example

{
   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.

Remove response

{
   response: true,
   log: "Object deleted",
   obj: {
      id: "5b929a13e7c7543ce399ea13",
      Phone: "491788046563",
      Anrede: "Herr",
      Vorname: "Peter",
      Nachname: "Müller",
      "Wann kontaktieren": "16 Uhr"
   }
}

2.3. GetAllLeads

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.

GetAllLeads response

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

2.4. GetLead

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.

3. 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

GetAllLeads response

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

API-Docs

1. How to Use

2. Funktionen

2.1. Import

Import example

Import response

2.2. Remove

Remove example

Remove response

2.3. GetAllLeads

GetAllLeads response

2.4. GetLead

3. Export

GetAllLeads response