Übergabeprotokoll

Das Übergabeprotokoll der Messenger-Plattform ermöglicht es zwei oder mehr Apps, an einer Unterhaltung teilzunehmen, indem sie die Kontrolle der Unterhaltung untereinander weitergeben. Das Übergabeprotokoll ist automatisch für Apps aktiviert, die eine Facebook-Seite abonniert haben.

Hinweis:Weiterleitung von Unterhaltungen ist jetzt verfügbar und wird in Kürze das Übergabeprotokoll ersetzen. Du solltest deine App so schnell wie möglich für die Nutzung der Weiterleitung von Unterhaltungen aktualisieren.

So funktioniert's

Eine Facebook-Seite oder ein professionelles Instagram-Konto kann mehrere Messaging-Apps verwenden, um mit Kunden oder an ihren Inhalten interessierten Personen zu kommunizieren. Beim Kundensupport können Kund*innen beispielsweise zu einem automatisierten Erlebnis gesendet werden. Wenn das Kundenproblem damit aber nicht gelöst werden kann, können Kund*innen zu einer anderen App mit Live-Supportmitarbeiter*innen geleitet werden. Um die Unterhaltung und ihre Metadaten von einer App zu einer anderen bzw. zwischen einer App und dem Postfach einer Facebook-Seite oder einem Instagram-Postfach zu übertragen, muss die Kontrolle über die Unterhaltung zwischen Apps weitergegeben werden. Diese Übertragung wird durch das Übergabeprotokoll ermöglicht.

Wenn Kund*innen eine Nachricht zum Start einer Unterhaltung senden, ist die Unterhaltung standardmäßig inaktiv. Apps erhalten per Webhooks eine Benachrichtigung, dass eine Nachricht eingegangen ist und auf eine Antwort wartet. Um diese Benachrichtigung zu erhalten, muss eine App die übergabespezifischen Webhooks abonnieren.

Während die Unterhaltung inaktiv ist, kann jede App die Kontrolle über die Unterhaltung übernehmen. Nur die App mit der Kontrolle über die Unterhaltung kann auf die Nachricht antworten. Die Kontrolle kann jeweils immer nur von einer App übernommen werden. Andere Apps können erst dann Nachrichten senden, wenn die App ihre Kontrolle freigibt. Nachdem eine App die Kontrolle freigegeben hat, wird die Unterhaltung wieder inaktiv. Dann kann die nächste App die Kontrolle übernehmen.

Die App, die die Unterhaltung kontrolliert, erhält Benachrichtigungen von den Messaging-Webhooks. Alle anderen Apps erhalten Benachrichtigungen von den übergabespezifischen Webhooks.

Wenn eine Unterhaltung 24 Stunden lang keine Aktivität verzeichnet, wird sie automatisch wieder inaktiv. Bei Bedarf kann eine kontrollierende App die Kontrolle länger als 24 Stunden behalten.

Wenn eine App, die keine Kontrolle über die Unterhaltung hat, versucht, eine Nachricht zu senden, wird ein 400-Fehler mit dem Untercode 2018300 zurückgegeben.

Primärer Empfänger

Wenn eingehende Nachrichten von einer bestimmten App bearbeitet werden sollen, kannst du diese App als primären Empfänger zuweisen. Der primäre Empfänger erhält alle neuen Nachrichten einer Unterhaltung, kann die Kontrolle an eine andere App bzw. ein anderes Facebook-Seitenpostfach oder Instagram-Postfach übergeben und die Kontrolle über eine Unterhaltung von einer anderen App übernehmen, falls erforderlich. Wenn eine andere App als der primäre Empfänger ihre Arbeit in der Unterhaltung abgeschlossen hat und die Kontrolle freigibt, wird die Unterhaltung inaktiv.

Wenn eine Person in einer inaktiven Unterhaltung eine neue Nachricht an deine Seite oder dein Konto sendet, erhält der primäre Empfänger die Kontrolle über die Unterhaltung. Er erhält dann eine Webhook-Benachrichtigung über die neue Nachricht.

Hinweis: Du musst keinen primären Empfänger festlegen.

Postfach

Das Postfach einer Facebook-Seite oder ein Instagram-Postfach kann nicht als primärer Empfänger festgelegt werden. Wenn du die Nachricht aber in den Hauptordner verschiebst oder eine Nachricht in einer Unterhaltung beantwortest, die nicht vom Postfach kontrolliert wird, übernimmt das Postfach die Kontrolle über die Unterhaltung. Wenn du eine Nachricht beantwortest, die im Postfach als Fertig markiert ist, bleibt die Kontrolle bei der zuvor kontrollierenden App oder dem primären Empfänger (falls festgelegt) oder sie wird freigegeben.

Einstiegspunkte für Unterhaltungen

Du kannst eine Unterhaltung einer bestimmten App zuweisen, wenn du Click-to-Messenger (CTM) als Einstiegspunkt für die Unterhaltung verwendest. Mit CTM können Unternehmen Unterhaltungen mit Kunden beginnen, um Leads zu generieren, die Markenbekanntheit zu steigern und mehr.

Beständiges Menü

Wenn kein primärer Empfänger festgelegt ist, kann jede App das Menü auf Seitenebene bestimmen. Wenn du eine primäre App eingerichtet hast, kann nur sie ein Menü auf Seitenebene festlegen oder löschen.

Die App mit der Kontrolle über die Unterhaltung kann das Menü auf Nutzerebene auch dann festlegen oder löschen, wenn die App nicht der primäre Empfänger ist. Wenn die Unterhaltung inaktiv ist, kann jede App das Menü auf Nutzerebene bestimmen.

Wenn Kund*innen eine Option in einem Menü auswählen, erhält die App, die das Menü erstellt hat, die Kontrolle über die Unterhaltung. Das liegt daran, dass die App, die das Menü erstellt hat, für die Verarbeitung dieser Daten konfiguriert ist.

Postback-Call to Action

Wenn Kund*innen auf einen Postback Call-To-Action (CTA) klicken, erhält die App, die den Postback-CTA erstellt hat, die Kontrolle über die Unterhaltung, selbst wenn diese zuvor bei einer anderen App lag. Das liegt daran, dass die App, die den Postback-CTA erstellt hat, für die Verarbeitung dieser Daten konfiguriert ist.

Kundenumfragen

Wenn eine Umfrage gesendet wird, während eine andere App die Unterhaltung kontrolliert, wird die Umfrage erst zugestellt, wenn die App die Kontrolle freigibt und die Unterhaltung inaktiv ist.

Komponenten

Die folgenden Komponenten sind erforderlich, um das Übergabeprotokoll für Messaging-Apps, die deine Facebook-Seite abonniert hat, erfolgreich zu implementieren.

Zugriffsschlüssel

Für Aufrufe der Übergabeprotokoll-Endpunkte ist ein Seiten-Zugriffsschlüssel erforderlich, der von einer Person angefordert wurde, die die MODERATE-Aufgabe auf der Seite ausführen kann.

App-Review

Der App-Review ist für Apps erforderlich, auf die Folgendes zutrifft:

Sie werden von Personen verwendet, die keine Rolle in der App haben.
Sie ermöglichen, dass Mitarbeiter*innen Kundenfragen beantworten.

„Human Agent“-Funktion

Eine App kann Nachrichten auch ohne Kontrolle über die Unterhaltung an Personen senden, wenn die App im App-Review die Genehmigung für die „Human Agent“-Funktion erhalten hat und die Nachricht mit dem Human Agent-Tag markiert wurde. Das ist das einzige Szenario, bei dem eine Nachricht von einer App gesendet werden kann, die nicht die Kontrolle über die Unterhaltung hat.

Berechtigungen

Die Berechtigung pages_messaging ist erforderlich, damit Apps die Berechtigung zum Zugriff auf Nachrichtendaten anfragen können.

Webhooks

Das Übergabeprotokoll umfasst zwei Sets von Webhooks, die eine App abonnieren sollte: die Messaging-Webhooks und die Standby-Webhooks. Welche Benachrichtigungen eine App erhält, hängt von der Unterhaltungskontrolle ab. Die App mit der Kontrolle über eine Unterhaltung erhält die Benachrichtigungen der Messaging-Webhooks. Apps ohne Kontrolle über die Unterhaltung erhalten die Benachrichtigungen der Standby-Webhooks.

Häufige Anwendungsfälle

Kund*innen-Support

Ein Unternehmen verwendet eine App für automatisierte Antworten auf häufig gestellte Fragen, leitet Kund*innen aber an eine andere App für Live-Support weiter, wenn das automatisierte Erlebnis das Kundenproblem nicht löst. Die automatisierte App wird als primärer Empfänger festgelegt und ist somit Eigentümer aller Unterhaltungen. Wenn ein*e Live-Supportmitarbeiter*in der Unterhaltung beitreten muss, kann die Live-Support-App die Kontrolle über die Unterhaltung anfordern. Wenn die Live-Mitarbeiter-App die Unterhaltung abgeschlossen hat, wird die Kontrolle wieder an die automatisierte App abgegeben. Wenn die Live-Mitarbeiter-App mehr Zeit für die Lösung eines Kundenproblems benötigt, kann die App eine Verlängerung anfordern. Beide Apps sollten die Webhooks abonnieren, damit die Unterhaltung richtig abläuft.

Marketingkampagne – Produkt-Leads

Ein Unternehmen startet eine Marketingkampagne und verwendet eine automatisierte App, um Leads zu qualifizieren oder Produktempfehlungen auf Basis eines Produktquiz abzugeben. Nach der Leadqualifizierung nutzt das Unternehmen das Postfach der Facebook-Seite oder das Instagram-Postfach, um potenzielle Kund*innen anzusprechen. Die automatisierte App wird als primärer Empfänger festgelegt und ist somit Eigentümer aller Unterhaltungen. Nachdem die automatisierte App die Leadqualifizierungsphase abgeschlossen hat, wird die Kontrolle über die Unterhaltung an das Postfach der Facebook-Seite oder das Instagram-Postfach übergeben. Wenn die Unterhaltung im Postfach der Facebook-Seite oder im Instagram-Postfach abgeschlossen ist, markiere sie als Fertig. Dadurch wird die Kontrolle über die Unterhaltung wieder an die primäre App übergeben. Beide Apps sollten die Webhooks abonnieren, damit die Unterhaltung richtig abläuft.

Marketingkampagne – Click-to-Messenger Ads

Ein Unternehmen startet eine Marketingkampagne und leitet potenzielle Kund*innen zu einer automatisierten App für ein bestimmtes Messenger-Erlebnis. Die automatisierte App wird als primärer Empfänger festgelegt und ist somit Eigentümer aller Unterhaltungen. Wenn ein*e Live-Supportmitarbeiter*in der Unterhaltung beitreten muss, kann die Live-Support-App die Kontrolle über die Unterhaltung anfordern. Wenn die Live-Mitarbeiter-App die Unterhaltung abgeschlossen hat, wird die Kontrolle wieder an die automatisierte App abgegeben. Wenn die Live-Mitarbeiter-App mehr Zeit für die Lösung eines Kundenproblems benötigt, kann die App eine Verlängerung anfordern. Beide Apps sollten die Webhooks abonnieren, damit die Unterhaltung richtig abläuft.

Best Practices

Wir empfehlen, dass du automatisierte Erlebnisse als primäre Empfänger-App und eventuelle Live-Mitarbeiter-Apps als nicht primäre Apps festlegst. Die Live-Mitarbeiter-App sollte die Standby-Ereignisse überwachen und nur bei Bedarf aktiv werden.
Verwende immer die Get Thread Control API, um zu prüfen, ob du die Kontrolle über den Thread hast oder nicht. Rufe dann andere APIs je nach Szenario auf. Unterbrich die Unterhaltung nicht, wenn du nicht die Kontrolle hast.
Stelle sicher, dass du keine Nachrichten an den Thread sendest, wenn eine andere App die Kontrolle über die Unterhaltung hat. Die primäre App sollte die Take Thread Control API nur wenn unbedingt nötig verwenden. Wenn es nicht dringend ist oder du als nicht primäre App fungierst, fordere die Thread-Kontrolle an.
Stelle sicher, dass du Ereignisse zum Anfordern der Thread-Kontrolle von anderen Apps wenn möglich immer zulässt und die Thread-Kontrolle an diese App übergibst. Wenn du die Thread-Kontrolle aus irgendeinem Grund nicht sofort übergeben kannst, sende mit der Pass Metadata API zusätzlichen Kontext an die anfordernde App und richte eine Warteschlange ein, um die Thread-Kontrolle zu übergeben, wenn du fertig bist.
Wenn du mit der Unterhaltung fertig bist, übergib die Thread-Kontrolle an eine App in der Warteschlange, die die Kontrolle zuvor angefordert hat, oder gib die Thread-Kontrolle frei, damit andere Apps den Thread übernehmen können. Andernfalls wird der Thread nach 24 Stunden automatisch freigegeben und inaktiv. Programmiere dieses Szenario und die zugehörigen Statusänderungen entsprechend.
Wenn du die Get Thread Control API aufrufst und feststellst, dass der Thread inaktiv ist, verwende die Request Thread Control, um die Kontrolle über den Thread zu übernehmen. Dann kannst du exklusiv ohne Unterbrechungen mit Nutzer*innen sprechen und die Unterhaltung dann freigeben.

Mehr dazu

Weitere Informationen zu den Komponenten des Übergabeprotokolls.

Nächste Schritte

Jetzt weißt du, wie das Übergabeprotokoll funktioniert. Führe nun die folgenden Schritte aus, um das Protokoll zu implementieren: