Skip to main content

Voraussetzungen für das Starten einer Confirmation

Hinterlegen eines Messaging Accounts​

Grundsätzliches​

Der SMS-Versand und -Empfang für einen Bestätigungsprozess in ConfirmationCheck erfolgt über einen SMS-Account und die dazugehörige Telefonnummer. Ein SMS-Account wird in ConfirmationCheck als Messaging Account angelegt.
ConfirmationCheck kann mit SMS-Accounts verwendet werden, die das Versenden von SMS via REST-Schnittstelle ermöglichen und bei denen eine bestimmte Empfangsadresse für eingehende Nachrichten konfiguriert werden kann.

In ConfirmationCheck können mehrere Messaging Accounts hinterlegt und für Bestätigungsprozesse genutzt werden.

Die Hinterlegung eines Messaging Accounts erfolgt in der Web-Oberfläche von ConfirmationCheck.

Einrichtung eines SMS-Accounts​

Die Einrichtung eines Messaging Accounts beginnt außerhalb der Applikation mit der Konfiguration eines SMS-Accounts. Sie benötigen von Ihrem SMS-Anbieter eine Rufnummer, die SMS empfangen kann.

Zudem müssen Webhooks für folgende Events eingerichtet werden:

  • Die Weiterleitung eingehender SMS für Ihre Rufnummer und
  • die Weiterleitung von Zustellungsbenachrichtigungen ausgehender SMS

an die für ConfirmationCheck vordefinierte Route.

Diese vordefinierte Route erhalten Sie bei Vertragsabschluss via Mail.

Die Bezeichnungen der Events können ebenfalls von Anbietern unterschiedlich gewählt sein. Die jeweiligen Bezeichnungen entnehmen Sie der Dokumentation Ihres SMS-Anbieters.

Bitte beachten Sie, dass die SMS-Anbieter unterschiedliche API Endpunkte und HTTP-Methoden für das Versenden von SMS definiert haben, die bei der Hinterlegung des Messaging Accounts in ConfirmationCheck benötigt werden. Die jeweiligen Informationen entnehmen Sie der Dokumentation Ihres SMS-Anbieters.

Elemente eines Messaging Accounts​

Ein Messaging Account setzt sich zusammen aus den folgenden Elementen:

  • Messaging Account Name: Name für den SMS-Account
  • Source Phone Number: Quell-Telefonnummer des SMS-Account
  • Messaging Service: SMS-Provider für den SMS-Account
  • Http-Method: Http-Methode, die die API des ausgewählten Messaging Dienstes zum Versenden einer SMS erwartet
  • Token: Token, das beim Aufrufen der API des Messaging-Dienstes zur Authentifizierung genutzt wird
  • Messaging Service API-URL: URL für den Aufruf der REST-API des SMS-Accounts
  • Forward URL (Optional): Http-Endpunkt, an den eingehende Nachrichten an den SMS-Account, unabhängig vom Bestätigungsprozess, weitergeleitet werden. Dieser Endpunkt muss POST-Anfragen mit dem Content-Type: application/json verarbeiten können.

Konfigurieren eines Templates für den Bestätigungsprozess​

Ein Template für eine Confirmation ist ein Set aus vorkonfigurierten SMS-Nachrichten. Diese dienen durch Hinterlegung von Parametern als Basis für individuelle SMS-Nachrichten.

Das Anlegen eines Templates erfolgt in der Web-Oberfläche von ConfirmationCheck.

Parameter​

In dem initial an den Smartphone-Nutzer zu sendenden Introduction Text sind individuelle Parameter optional. Für den vom Smartphone-Nutzer zurückzuschickenden Confirmation Text müssen Parameter hinterlegt werden. Parameter werden mit einem „$“ gekennzeichnet. Parameter können beim Starten eines Bestätigungsprozesses individuell für die Zielrufnummer mit Daten befüllt werden.

Elemente eines Templates​

  • Introduction Text: Text für die initiale Nachricht im Rahmen einer Confirmation an den Smartphone-Nutzer. Dieser Text ist optional parametrisierbar und kann beispielsweise eine Begrüßung mit Namen des Empfängers und näheren Informationen zum Kontext der Nachricht enthalten.

    Beispiel:

    Beispiel Introduction Text

  • Confirmation Text: Unter dem Einleitungstext in der initialen Nachricht im Rahmen einer Confirmation befindet sich standardmäßig ein Link. Sobald der Empfänger der Nachricht auf diesen Link klickt, wird bei ihm der im Confirmation Text konfigurierte Bestätigungstext als abschickbare SMS bereitgestellt. Im Confirmation Text müssen Parameter verwendet werden.

    Beispiel:

    Beispiel Confirmation Text

  • Try Again Message (Optional): Dieser Text wird als SMS im Rahmen einer Confirmation verschickt, wenn der Adressat während eines aktiven Bestätigungsprozesses eine SMS schickt, die vom erwarteten Bestätigungstext (Expected Message) abweicht. Die Try Again Message ist optional und nicht parametrisierbar.

    Beispiel:

    Beispiel Try Again Message

  • Resolved Message (Optional): Dieser Text wird als SMS im Rahmen einer Confirmation verschickt, nachdem der erwartete Bestätigungstext (Expected Massage) empfangen wurde. Die Resolved Message ist optional und nicht parametrisierbar.

    Beispiel:

    Beispiel Resolved Message

  • Failure Message (Optional): Dieser Text wird als SMS im Rahmen einer Confirmation verschickt, sofern der Bestätigungsprozess (die Confirmation) den Status „Timeout“, „Aborted“, „ResolvedIncorrectAnswer“ oder „Overwritten" erreicht.

    Beispiel:

    Beispiel Failure Message

  • Callback URL: In einem Template kann als Callback URL ein https-Endpunkt, der POST-Anfragen mit dem Content-Type: application/json verarbeiten kann, hinterlegt werden. Dort wird, falls definiert, nach jedem auf diesem Template basierenden beendeten Bestätigungsprozess der finale Confirmation-Status der Confirmation standardmäßig hingesendet. Beim Start einer Confirmation kann optional eine davon abweichende Callback URL angegeben werden.

  • Confirmation Expiration (min): Diese zeitliche Angabe bestimmt wie viele Minuten eine Confirmation aktiv ist, bevor sie automatisch in den Status „Timeout“ übergeht. Als Eingabewert wir hier eine Anzahl von Minuten (Wert zwischen 1 und 10.080) erwartet.

  • Active (Yes/No): Dieser Wert beschreibt, ob das Template für weitere Confirmations verwendet werden kann.

  • In Usage (Yes/No): Dieser Wert beschreibt, ob das Template bereits für Confirmations verwendet wurde.

Löschen und Editieren von Templates​

Ein Template kann in der Benutzeroberfläche jederzeit editiert oder gelöscht werden.

Wird ein Template editiert oder gelöscht während eine auf diesem Template basierende Confirmation aktiv ist, wird diese Confirmation mit der ursprünglichen Templatekonfiguration abgeschlossen. Spätere Confirmations nutzen die neue Konfiguration des Templates bzw. müssen bei Löschung des Templates auf einem anderen Template basieren.