Kontoverknüpfung

Die Kontoverknüpfung unterscheidet sich von anderen Webansicht-Funktionen, die auf der Messenger-Plattform verfügbar sind. Sie kann nur über Anmelde-Buttons gestartet werden und nicht vom beständigen Menü des Bots, von URL-Buttons, von einem bereits geöffneten Webansichtablauf oder einer Chat-Plugin aus.

Entwickler*innen, die diese Features nutzen, können nun die Nutzer*innen-ID sicher über die getContext()-Funktion in den Messenger-Erweiterungen abrufen. Bots können damit das Konto des*der Nutzer*in verknüpfen oder die Erfahrung personalisieren.

Die Kontoverknüpfung wird aktuell nur in der Messenger-App in iOS und Android unterstützt.

Wenn Nutzer*innen eine Unterhaltung mit deinem Unternehmen beginnen, möchtest du sie eventuell als Kund*innen identifizieren, die bereits über ein Konto bei deinem Unternehmen verfügen. Zu diesem Zweck haben wir ein gesichertes Protokoll erstellt, mit dem du die Identitäten der Messenger-Nutzer*innen mit denen der Unternehmensnutzer*innen verknüpfen bzw. diese Verknüpfung aufheben kannst.

Über die Kontoverknüpfung kannst du Nutzer*innen einladen, sich mit deinem Authentifizierungsvorgang anzumelden. Daraufhin wird eine seitenspezifische Messenger-ID vergeben. Daraufhin kannst du deinen Nutzer*innen ein sichereres, persönlicheres und relevanteres Erlebnis bieten.

Inhalt

Verknüpfungsvorgang
Rückruf
Webhook-Event
Endpunkt zum Aufheben der Kontoverknüpfung
Best Practices

Verknüpfungsvorgang

Der Kontoverknüpfungsvorgang umfasst einige einfache Schritte.

Registriere über den Login-Button eine Rückruf-URL.
Die Messenger-Plattform ruft die registrierte URL auf, wenn Nutzer*innen den Kontoverknüpfungsvorgang starten. Die Parameter redirect_uri und account_linking_token werden an den registrierten Rückruf angehängt.
Leite Nutzer*innen nach Abschluss der Verknüpfung an den von redirect_uri angegebenen Ort um und hänge einen (von dir definierten) authorization_code-Parameter an, um die Verknüpfung zu bestätigen.
Optional kannst du die seitenspezifische ID der Nutzer*innen über den Kontoverknüpfungs-Endpunkt abrufen. Du solltest diesen Schritt nur in Sonderfällen verwenden, wenn du die seitenspezifische ID der Nutzer*innen im Rahmen des Verknüpfungsprozesses benötigst.

Das Aufheben der Kontoverknüpfung kann wie folgt gestartet werden:

durch die Nutzer*innen beim Tippen auf den Logout-Button des*der Entwickler*in
durch das Unternehmen über den Endpunkt zum Aufheben der Kontoverknüpfung

Rückruf

Die Kontoverknüpfungs-URL wird von der Messenger-Plattform aufgerufen, wenn Nutzer*innen die Kontoverknüpfung auslösen. Die Parameter redirect_uri und account_linking_token werden an den URL-Rückruf angehängt.

<yourAccountLinkingUrl>
  ?account_linking_token=ACCOUNT_LINKING_TOKEN
  &redirect_uri=CALLBACK_URL

Bei erfolgreicher Kontoverknüpfung musst du den Vorgang abschließen, indem du den Browser an die im redirect_uri-Parameter angegebene URL weiterleitest und einen eigens definierten authorization_code-Parameter anhängst. Dabei ist zu beachten, dass die URL bereits Parameter enthalten kann, weshalb du den Autorisierungscode folgendermaßen anhängen solltest:

<redirect_uri>
  &authorization_code=AUTHORIZATION_CODE

Wenn die Kontoverknüpfung nicht erfolgreich ist, leite den Browser zu der redirect_uri weiter, die dir als Parameter übergeben wurde, aber hänge authorization_code nicht an.

Parameter

Parametername	Beschreibung
`redirect_uri`	Umleitungs-URI, die von Messenger hinzugefügt wird. Du musst den Browser am Ende des Authentifizierungsvorgangs zu diesem Ort umleiten. Sie kann eventuell URL-codierte Parameter enthalten.
`account_linking_token`	Kurzlebiges, von Messenger übergebenes Token, das du im Rahmen des Umleitungsschemas zurücksenden musst. Dieses Token ist nur 5 Minuten lang gültig, wird verschlüsselt und ist für alle Nutzer*innen eindeutig. Mit diesem Token kannst du den Endpunkt zum Abrufen der seitenspezifischen ID aufrufen, um die zugehörige seitenspezifische ID abzurufen.
`authorization_code`	Von dir bereitgestellter Code zur Bestätigung einer erfolgreichen Verknüpfung. Die Messenger-Plattform sendet diesen Code zusammen mit der seitenspezifischen ID desder Nutzerin an das Kontoverknüpfungs-Webhook-Event zurück. Wenn du diesen Parameter nicht übergibst, wird der Verknüpfungsprozess abgebrochen.

Webhook-Event

Bei einem erfolgreichen Verknüpfungsvorgang wird das Kontoverknüpfungs-Event ausgelöst, um die seitenspezifische ID des*der Nutzer*in auszuliefern.

Du musst dich für den Rückruf zum Kontoverknüpfungs-Event registrieren. Wenn du dieses Webhook-Event nicht bestätigst, wird der Verknüpfungsprozess abgebrochen.

Endpunkt zum Abrufen der seitenspezifischen ID

In manchen Fällen musst du die seitenspezifische ID des*der Nutzer*in während des Verknüpfungsvorgangs abrufen. Zu deiner Unterstützung stellen wir einen Endpunkt zum Abrufen der seitenspezifischen ID bereit, über den du die seitenspezifische ID des*der Nutzer*in mit einem gültigen und nicht abgelaufenen account_linking_token abrufen kannst.

Anfrage

curl -X GET "https://graph.facebook.com/v2.6/me?access_token=PAGE_ACCESS_TOKEN \
      &fields=recipient \
      &account_linking_token=ACCOUNT_LINKING_TOKEN"

Antwort

{
  "id": "PAGE_ID",
  "recipient": "PSID"
}

Endpunkt zum Aufheben der Kontoverknüpfung

In manchen Fällen musst du die Verknüpfung der seitenspezifischen ID des*der Nutzer*in programmgesteuert in deinem Backend aufheben. Zu deiner Unterstützung stellen wir einen Endpunkt zum Aufheben der Verknüpfung der seitenspezifischen ID bereit, über den du die Kontoverknüpfung des*der Nutzer*in mit einer seitenspezifischen ID aufheben kannst.

Anfrage

curl -X POST -H "Content-Type: application/json" -d '{
   "psid":"PSID"
}' "https://graph.facebook.com/v2.6/me/unlink_accounts?access_token=PAGE_ACCESS_TOKEN"

Antwort

{
  "result": "unlink account success"
}

Best Practices

Verwende die Kontoverknüpfung, wenn du mit einem System für Nutzer*innenkonten arbeitest, das über Messenger hinausgeht.

Lasse Personen ein Konto in Messenger erstellen, das auch an anderen Stellen verfügbar ist.

Verlange eine Anmeldung, wenn dies für den Kontext relevant ist – also wenn deine Bot-Nutzer*innen darin auch einen Vorteil erkennen können.

Überlege dir, wie dein Bot sich verhalten soll, wenn Nutzer*innen die Anmeldung ablehnen.

Achte auf eine klare Bestätigung und eine freundliche Begrüßung nach der Anmeldung.

Verwende die Kontoverknüpfung nicht, wenn Nutzer*innen nur über Messenger mit dir interagieren. Du kannst Kontodaten über die Thread-ID speichern.

Verlange die Kontoverknüpfung nicht von Anfang an, wenn es sich vermeiden lässt. Lasse die Nutzer*innen deinen Bot erst ausprobieren.

Empfohlener Designablauf

Fordere die Anmeldung mit einer Nachricht an, die unseren Button „Verknüpfung des Kontos“ enthält.
Zeige deine Anmeldeseite (einschließlich der Option „Konto erstellen“) in der Webansicht für die Kontoverknüpfung an. Achte darauf, dass die Seite auf Bildschirmen von Mobilgeräten gut aussieht und funktioniert.
Zeige nach der erfolgreichen Anmeldung eine Bestätigungsnachricht in der Webansicht an. Nutzer*innen müssen diese Nachricht anschließend selber schließen.
Schließe daran mit einem freundlichen Dankeschön und/oder den nächsten Schritten im Thread an, inklusive einer Abmeldeoption.