Webhooks in Nachrichten-Vorlagen

Generelle Informationen

Was sind Webhook-Links in Nachrichten?

Webhook-Links ermöglichen es, direkt aus Nachrichten-Vorlagen heraus Webhooks aufzurufen. Dies erlaubt es, interaktive Links in E-Mails einzubetten, über die Kunden oder Mitarbeiter Aktionen ausführen können, ohne sich in DocBee anmelden zu müssen.

Wann sollten Sie Webhook-Links in Nachrichten verwenden?

Falls einer oder mehrere der folgenden Punkte zutreffen, empfehlen wir den Einsatz von Webhook-Links in Nachrichten:

• Sie möchten, dass Kunden Aktionen direkt aus E-Mails heraus ausführen können (z.B. Problem-Bestätigung, Daten erfassen)
• Sie benötigen strukturierte Datenerfassung über Protokolle ohne Kunden-Login
• Sie wollen den Workflow vereinfachen, indem Sie Links direkt in Nachrichten einbetten
• Sie möchten automatisierte Prozesse mit Benutzerinteraktion kombinieren

Weitere Informationen finden Sie in der Nachrichten-Dokumentation und der Webhooks-Dokumentation.

Grundlagen

Der docbee_webhooklink Tag

Mit dem docbee_webhooklink Tag können Sie Webhook-Links direkt in Nachrichten-Vorlagen erstellen. Dieser Tag wird innerhalb der Nachrichten-Logik verwendet und generiert einen klickbaren Link, der den entsprechenden Webhook aufruft.

Wichtige Parameter:

Parameter	Pflichtfeld	Beschreibung
id	Ja	ID des Webhooks
personInChargeId	Nein*	ID eines Benutzers oder Queue
customerId	Nein*	ID des Kunden
locationId	Nein	ID des Kunden-Standorts
contactId	Nein	ID des Kunden-Kontakts
ticketId	Nein	ID eines Vorgangs
docBeeDocumentId	Nein	ID einer Leistung
name	Nein	Optionaler Name des Links
style	Nein	Optionale CSS-Styles für die Darstellung des Links

*Bei Protokoll-Webhooks muss die personInChargeId und die customerId gesetzt werden und Queues sind nicht erlaubt als Verantwortlicher.

Hinweis: Bei einem Protokoll-Webhook wird immer die Verknüpfung zum Vorgang hergestellt, auch wenn dieser geschlossen sein sollte. Der Vorgang verbleibt im abgeschlossenen Zustand.

Weitere Details finden Sie in der vollständigen Dokumentation zum docbee_webhooklink Tag.

Beispiel 1: Problem-Bestätigung über Vorgangs-Nachricht

Szenario

Ein Kunde meldet ein Problem. Nachdem das Problem behoben wurde, soll der Kunde bestätigen können, dass alles funktioniert, indem er auf einen Link in einer E-Mail klickt. Diese Bestätigung wird dann als Nachricht an den Vorgang angehängt.

Schritt-für-Schritt-Anleitung

Schritt 1: Webhook anlegen

1. Navigieren Sie zu Administration > Webhooks > Liste
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "Problem gelöst bestätigen")
4. Wählen Sie als Typ den Typ Nachricht
5. Wählen Sie eine Nachrichten-Vorlage aus, die verwendet werden soll, wenn der Webhook aufgerufen wird
6. Speichern Sie den Webhook

Hinweis: Notieren Sie sich die ID des Webhooks, da Sie diese später in der Nachrichten-Vorlage benötigen. Sie finden die ID in der Browser Adresszeile.

Schritt 2: Nachrichten-Vorlage mit Webhook-Link erstellen

1. Navigieren Sie zu Administration > Nachrichten > Vorlagen
2. Erstellen Sie eine neue Nachrichten-Vorlage oder bearbeiten Sie eine bestehende
3. Wählen Sie als Typ einen passenden Typ aus (z.B. Nachrichtenversand (Vorgang))
4. Geben Sie einen Betreff ein (z.B. "Problem sollte behoben sein - Bitte bestätigen")
5. Fügen Sie im Inhalt folgenden Code ein:

Sehr geehrte Damen und Herren,

das Problem sollte nun behoben sein. Bitte bestätigen Sie dies, indem Sie auf den folgenden Link klicken:

<docbee_webhooklink id='[WEBHOOK_ID]'
                    ticketId='ticket.id' 
                    name='Problem gelöst bestätigen' />

Mit freundlichen Grüßen
Ihr DocBee Team

Wichtig: Ersetzen Sie [WEBHOOK_ID] mit der tatsächlichen ID des in Schritt 1 erstellten Webhooks.

Schritt 3: Nachricht versenden

Wenn Sie nun eine Nachricht an einen Vorgang versenden und diese Nachrichten-Vorlage verwenden, wird der Webhook-Link automatisch in die E-Mail eingefügt. Der Kunde kann auf den Link klicken, um die Bestätigung zu senden.

Wie funktioniert es?

• Beim Klick auf den Link wird der Webhook aufgerufen
• Der Webhook erstellt eine Nachricht an den Vorgang (basierend auf der im Webhook hinterlegten Nachrichten-Vorlage)
• Die Nachricht wird automatisch mit dem Vorgang verknüpft
• Der Verantwortliche des Vorgangs wird über die Bestätigung informiert

Beispiel 2: Protokoll-Webhook für strukturierte Datenabfrage

Szenario

Ein Kunde benötigt einen neuen AD-Benutzer. Statt die Daten per E-Mail zu senden, soll der Kunde ein strukturiertes Formular (Protokoll) ausfüllen können. Der Link zum Formular wird in einer E-Mail versendet.

Schritt-für-Schritt-Anleitung

Schritt 1: Protokoll-Muster erstellen

1. Navigieren Sie zu Administration > Protokolle > Muster
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "Neuer AD-Benutzer")
4. Fügen Sie die benötigten Felder hinzu (z.B. Vorname, Nachname, E-Mail, Abteilung, etc.)
5. Speichern Sie das Protokoll-Muster
6. Geben Sie das Protokoll-Muster frei

Schritt 2: Webhook anlegen

1. Navigieren Sie zu Administration > Webhooks > Liste
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "AD-Benutzer Daten erfassen")
4. Wählen Sie als Typ den Typ Protokoll
5. Wählen Sie das in Schritt 1 erstellte Protokoll-Muster aus
6. Speichern Sie den Webhook

Hinweis: Notieren Sie sich die ID des Webhooks, da Sie diese später in der Nachrichten-Vorlage benötigen.

Schritt 3: Nachrichten-Vorlage mit Protokoll-Webhook-Link erstellen

1. Navigieren Sie zu Administration > Nachrichten > Vorlagen
2. Erstellen Sie eine neue Nachrichten-Vorlage oder bearbeiten Sie eine bestehende
3. Wählen Sie als Typ einen passenden Typ aus (z.B. Nachrichtenversand (Vorgang))
4. Geben Sie einen Betreff ein (z.B. "Bitte AD-Benutzer Daten erfassen")
5. Fügen Sie im Inhalt folgenden Code ein:

Sehr geehrte Damen und Herren,

bitte füllen Sie das folgende Formular aus, um die Daten für den neuen AD-Benutzer zu erfassen:

<docbee_object input='ticket.customer' var='ticketCustomer'>
<docbee_object input='ticket.owner' var='ticketOwner'>
<docbee_webhooklink id='[WEBHOOK_ID]' 
                    personInChargeId='ticketOwner.id' 
                    customerId='ticketCustomer.id' 
                    ticketId='ticket.id' 
                    name='AD-Benutzer Daten erfassen' />
</docbee_object>
</docbee_object>

Mit freundlichen Grüßen
Ihr DocBee Team

Wichtig: Ersetzen Sie [WEBHOOK_ID] mit der tatsächlichen ID des in Schritt 2 erstellten Webhooks.

Wichtig: Bei Protokoll-Webhooks müssen personInChargeId und customerId zwingend gesetzt werden.

Schritt 4: Nachricht versenden

Wenn Sie nun eine Nachricht an einen Vorgang versenden und diese Nachrichten-Vorlage verwenden, wird der Protokoll-Webhook-Link automatisch in die E-Mail eingefügt. Der Kunde kann auf den Link klicken, um das Protokoll auszufüllen.

Wie funktioniert es?

• Beim Klick auf den Link wird der Protokoll-Webhook aufgerufen
• Der Kunde sieht ein Formular basierend auf dem Protokoll-Muster
• Nach dem Ausfüllen wird ein Protokoll erstellt und mit dem Vorgang verknüpft
• Der Verantwortliche des Vorgangs wird über das neue Protokoll informiert
• Das Protokoll kann später als PDF exportiert werden

Best Practices

Wann welche Webhook-Typen verwenden?

Webhook-Typ	Verwendungszweck
Nachricht	Wenn eine einfache Bestätigung oder Rückmeldung benötigt wird
Protokoll	Wenn strukturierte Daten erfasst werden sollen (z.B. Formulare, Checklisten)
Vorgang	Wenn ein neuer Vorgang erstellt werden soll
Leistung	Wenn eine neue Leistung erstellt werden soll
Automatisierung	Wenn komplexe Automatisierungen ausgelöst werden sollen, z.B. Vorgang ändern

Wichtige Hinweise zu Protokoll-Webhooks

• personInChargeId und customerId sind Pflichtfelder: Bei Protokoll-Webhooks müssen beide Parameter gesetzt werden
• Queues sind nicht erlaubt: Als Verantwortlicher kann nur ein Benutzer, nicht aber eine Queue verwendet werden
• Verknüpfung zum Vorgang: Das Protokoll wird automatisch mit dem Vorgang verknüpft, auch wenn dieser geschlossen ist

Tipps zur Gestaltung der Links

• Verwenden Sie aussagekräftige Namen: Der name-Parameter sollte klar beschreiben, was beim Klick passiert
• Nutzen Sie CSS-Styles: Mit dem style-Parameter können Sie Links im HTML hervorheben (z.B. style='color:#28a745; font-weight:bold;' für grüne, fette Links)
• Testen Sie die Links: Stellen Sie sicher, dass alle benötigten Parameter korrekt gesetzt sind

Beispiel für verschiedene Link-Styles

<!-- Grüner Link für Bestätigungen -->
<docbee_webhooklink id='1' name='Bestätigen' style='color:#28a745; font-weight:bold;' />

<!-- Blauer Link für Formulare -->
<docbee_webhooklink id='2' name='Formular ausfüllen' style='color:#007bff; font-weight:bold;' />

<!-- Roter Link für wichtige Aktionen -->
<docbee_webhooklink id='3' name='Wichtig' style='color:#dc3545; font-weight:bold; text-decoration:underline;' />

FAQ

Warum funktioniert mein Webhook-Link nicht?

Mögliche Ursachen:

1. Falsche Webhook-ID: Überprüfen Sie, ob die ID im docbee_webhooklink Tag korrekt ist
2. Fehlende Parameter: Bei Protokoll-Webhooks müssen personInChargeId und customerId gesetzt sein
3. Webhook wurde gelöscht: Prüfen Sie, ob der Webhook noch in der Webhook-Liste vorhanden ist
4. Falsche Objekt-Referenzen: Stellen Sie sicher, dass die verwendeten Objekte (z.B. ticket.customer) existieren

Warum erhalte ich einen Fehler bei Protokoll-Webhooks?

Protokoll-Webhooks haben spezielle Anforderungen:

• personInChargeId ist Pflicht: Dieser Parameter muss gesetzt werden und darf keine Queue sein
• customerId ist Pflicht: Dieser Parameter muss gesetzt werden
• Verknüpfung zum Vorgang: Das Protokoll wird automatisch mit dem Vorgang verknüpft

Stellen Sie sicher, dass beide Parameter korrekt gesetzt sind:

<docbee_object input='ticket.customer' var='ticketCustomer'>
<docbee_object input='ticket.owner' var='ticketOwner'>
<docbee_webhooklink id='[WEBHOOK_ID]' 
                    personInChargeId='ticketOwner.id' 
                    customerId='ticketCustomer.id' 
                    ticketId='ticket.id' />
</docbee_object>
</docbee_object>

Wie kann ich die Webhook-ID herausfinden?

Die Webhook-ID finden Sie in der Webhook-Liste unter Administration > Webhooks > Liste. Die ID wird in der Liste angezeigt oder kann über die Aktionen des Webhooks eingesehen werden.

Kann ich mehrere Webhook-Links in einer Nachricht verwenden?

Ja, Sie können mehrere docbee_webhooklink Tags in einer Nachrichten-Vorlage verwenden. Jeder Link kann zu einem anderen Webhook führen.

Beispiel:

Bitte wählen Sie eine Aktion:

<docbee_webhooklink id='1' name='Problem gelöst' />
<docbee_webhooklink id='2' name='Problem besteht weiterhin' />

Werden die Links in HTML-E-Mails korrekt angezeigt?

Ja, die Webhook-Links werden in HTML-E-Mails als klickbare Links dargestellt. Der name-Parameter wird als Link-Text verwendet, und der style-Parameter wird als CSS-Style angewendet.

Kann ich Webhook-Links auch in Text-E-Mails verwenden?

Ja, Webhook-Links funktionieren auch in Text-E-Mails. Der Link wird als URL dargestellt, die der Empfänger anklicken kann.