API-Docs

Hereby we provide you our API-Functions
and give all additional information

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.

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 Strin,
Boolen
Ist optional und enthält den Wert, der in dataconnect geschrieben werden soll. Wenn kein value mitgegeben wird, wird die answer in dataconnect geschrieben.

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.



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.

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.



2.3. GetAllLeads

Um den aktuellen Stand der aktiven Leads zu erhalten.

URL Methode Content-Type
https://server.sales-q.com:8000/remove 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.

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].typ String Unterscheidet zwischen Chat, Bildern oder anderen Dateien.
chathistory[x].direction String Beschreibt, ob die Nachricht eingehend oder ausgehend ist.
chathistory[x].body String Enthält die Nachricht.

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

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"
        },
        {
          "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"
        }
      ]
    }
  ]
}
{
                 imported: true,
                 log: "imported the leads",
                 ids: [
                   {
                     Phone: "491788046563",
                     id: "5b929a13e7c7543ce399ea12"
                   },
                   {
                     Phone: "49123456789",
                     id: "5b929a13e7c7543ce399ea13",
                     mappingId: "13e7a47d49f92e13e76183ad"
                   }
                 ]
                }