REST-Trigger

👨‍💻️ Was ist ein REST-Trigger?

Der REST-Trigger-API-Endpunkt für Kampagnen ermöglicht es Ihnen, neue Empfänger Ihrer Kampagnen dynamisch hinzuzufügen, indem Sie einen einfachen HTTP-POST an die Trigger-API senden.

Über den REST-Trigger-API-Endpunkt können Sie das Kampagnensystem von ngSurvey einfach mit beliebigen Drittanbietersystemen integrieren und automatisieren, die Einladung zur Umfrage dynamisch versenden müssen. Sie könnten ngSurvey beispielsweise an ein Ticket-System anbinden, das bei Schließung eines Tickets automatisch Zufriedenheitsumfrage-Einladungen verschickt.

📨 Trigger-Einrichtung

Um Ihren Trigger einzurichten, müssen Sie eine laufende Kampagne erstellen. Sobald diese Kampagne eingerichtet ist, können Sie den Link zum Trigger über den REST-Trigger-Bildschirm aufrufen.

Dort finden Sie den HTTP-Trigger-Link, den Sie verwenden können, um neue Empfänger in Ihre Kampagnen-Warteschlange einzureihen. Der Kampagnen-Trigger-Bildschirm ermöglicht Ihnen außerdem, die Standardnachricht zu ändern, die als Einladungsvorlage für alle Empfänger verwendet wird, die über den Trigger eingereiht werden.

🚀 Wie man den REST-Trigger verwendet

Der API-Endpunkt verlangt einen HTTP POST sowie einen Authorization-Header mit Ihrem API key als Wert, vorausgehend mit dem Präfix Bearer.

Der Body Ihres HTTP-POSTs muss unter Verwendung der folgenden JSON-Struktur definiert werden

{
  "recipients": string[],
  "anonymous": boolean,
  "clearExistingBatches": boolean,
  "daysThreshold": number,
  "pipeParameters": { string:string },
  "mailingTemplateId": string,
  "message": {
    "mailingFrom": string,
    "mailingFromName": string
    "mailingSubject": string
    "mailingMessage": string
 }
}

🔅 Trigger-API-Eigenschaften

• recipients Ist die Liste der Empfänger, die dem Kampagnen-Batch hinzugefügt werden. Verwenden Sie E-Mails, wenn Ihre Kampagne auf E-Mails basiert, Telefonnummern, wenn sie auf SMS basiert, und verwenden Sie Panelist Ids, wenn Sie eine Panel-basierte Kampagne haben.

• anonymous verknüpft die E-Mail des Befragten nicht mit den Antworten des Befragten und löscht die E-Mail aus der Datenbank, sobald der Befragte die Umfrage abgeschlossen hat. Diese Option ist nur gültig, wenn Sie den Trigger in einer E-Mail-basierten Kampagne verwenden.

• clearExistingBatches löscht aus dem Versand-Batch alle vorherigen Einträge des Empfängers. Beachten Sie, dass nur der Eintrag im Versand-Batch entfernt wird; vorhandene Umfrageantworten werden nicht gelöscht.

• daysThreshold Optional. Ist die Anzahl der Tage, nach denen ein Empfänger wieder zum Versand-Batch hinzugefügt werden kann. Lassen Sie diesen Wert auf null, können Ihre Empfänger jederzeit dem Versand-Batch hinzugefügt werden. Sie können den Wert auch auf 0 setzen, um den Empfänger nur hinzuzufügen, wenn es keinen vorherigen Eintrag im Versand-Batch gibt.

• pipeParameters Optional. Ermöglicht Ihnen die Definition dynamischer Name/Wert-Parameter, die in der Einladungsnachricht ersetzt werden.

• mailingTemplateId Optional. Ermöglicht Ihnen die Verwendung einer bestehenden Mailing-Vorlage als Einladungstext.

• message Optional. Ermöglicht es Ihnen, die Standard-Einladungsnachricht des Triggers mit Ihrer eigenen Nachricht zu überschreiben. Beachten Sie, dass dadurch auch die Eigenschaft mailingTemplateId überschrieben wird.

Wenn Sie Piping, Mailing-Vorlagen oder eine benutzerdefinierte Nachricht für Ihren Trigger verwenden, beachten Sie bitte, dass ngSurvey für jeden Empfänger einen neuen Eintrag für die Einladungsnachricht in der Datenbank anlegt. Daher empfehlen wir, clearExistingBatches auf true zu setzen, wenn Sie eine Automation mit einer hohen Anzahl von Trigger-Aufrufen ausführen, die im Zeitverlauf dieselben Empfänger enthält.

Wenn Sie eine Automation mit einer hohen Anzahl von Trigger-Aufrufen betreiben, die wiederkehrende Empfänger beinhaltet, empfehlen wir, die Eigenschaft clearExistingBatches so zu setzen, dass für jeden Empfänger nur ein einzelner Batch-Sendeeintrag in der ngSurvey-Datenbank verbleibt.

🚰 Piping-Werte

Mit der optionalen Eigenschaft pipeParameters können Sie einen Satz von Werten angeben, die zur Laufzeit in der Einladung nachrichtlich eingefügt werden, die an die Empfänger gesendet wird. Pipe-Tags in Ihrer Einladungsnachricht müssen wie folgt formatiert sein: [*propertyname*]

  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  }

Um den prop1-Wert in Ihrer Einladungsnachricht zu pipen, müssen Sie den folgenden Tag hinzufügen, der zur Laufzeit durch value1 ersetzt wird.

[*prop1*]

Wenn Sie die Einladung aus einem Ticketing-System auslösen, könnten Sie beispielsweise die Ticketnummer in den Umfragelink Ihrer Einladungsnachricht pipen und dieses Ticket in einem versteckten Feld innerhalb der Umfrage speichern.

CURL / Body-Beispiel

curl -X POST "http://yoursite/api/Campaigns/yourcampaign/trigger" -H  "accept: */*" -H  "Authorization: Bearer YOURAPIKEY" -H  "Content-Type: application/json-patch+json" -d "{\"recipients\":[\"[email protected]\",\"[email protected]\"],\"anonymous\":false,\"clearExistingBatches\":false,\"daysThreshold\":null,\"pipeParameters\":{\"prop1\":\"value1\",\"prop2\":\"value2\",\"prop3\":\"value3\"},\"message\":null,\"mailingTemplateId\":null}"

{
  "recipients": ["[email protected]", "[email protected]"],
  "anonymous": false,
  "clearExistingBatches": false,
  "daysThreshold": null,
  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  },
  "message": null,
  "mailingTemplateId": null
}