Bewertungseinladungen per API verwalten – Yext Help

Die Generierung von Bewertungen mit Yext ermöglicht es Unternehmen, ihren Kund*innen Einladungen per E-Mail und SMS zu senden, um sie zur Abgabe einer Bewertung über die Review Balancing URL aufzufordern. Diese URL leitet Nutzer*innen zu Bewertungsseiten von Drittanbietern und/oder zu Ihrer Seite zur Sammlung von Bewertungen aus erster Hand, abhängig von der Verteilung, die Sie für den Ausgleichsalgorithmus von Bewertungen festgelegt haben. Mehr über den Ausgleichsalgorithmus von Bewertungen erfahren Sie im Leitfaden Erste Schritte mit Reviews.

Sie können die Bewertungseinladungen per API verwenden, um eine Integration mit einem externen System durchzuführen und Einladungen programmgesteuert zu verwalten.

Integrationsmuster

Die meisten Integrationen für Bewertungseinladungen verwenden eines von zwei Mustern.

Push: Ihr externes System benachrichtigt Ihre Anwendung sofort, wenn ein Auslöser auftritt, woraufhin Ihre Anwendung eine Einladung erstellt. Häufige Push-Auslöser sind:

Ein*e Kund*in erhält ein Produkt und das Abwicklungssystem signalisiert, dass die Zustellung abgeschlossen ist.
Ein*e Kund*in schließt einen Kauf im Geschäft ab und das Kassensystem signalisiert, dass die Transaktion abgeschlossen ist.
Ein*e Patient*in schließt einen Besuch ab und das Terminplanungssystem signalisiert, dass der Terminstatus aktualisiert wurde.

Pull: Ihre Anwendung ruft regelmäßig Einladungen auslösende Daten ab, anstatt eine Benachrichtigung in Echtzeit zu erhalten. Pull-Integrationen sind üblich, wenn das externe System keine Webhooks für den entsprechenden Auslöser unterstützt oder wenn Einladungsdaten nach einem Zeitplan an einen FTP-Standort exportiert werden.

API-Endpunkte Bewertungseinladungen

Endpunkt	Beschreibung	URL
Bewertungseinladungen: Erstellen	Erstellt eine neue Bewertungseinladung	POST https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites
Bewertungseinladungen: Abrufen/Auflisten	Ruft bestehende Bewertungseinladungen ab	GET https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites
Bewertungseinladungen: Aktualisieren	Aktualisiert eine bestehende Bewertungseinladung	PUT https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid}
Bewertungseinladungen: Löschen	Löscht eine bestehende Bewertungseinladung	DELETE https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid}

Einladungsfelder

Eine Einladung enthält die folgenden zentralen Felder. Zusätzliche Felder sind im Anfragetext erforderlich. Alle Informationen dazu finden Sie in der API-Dokumentation.

Feld	Beschreibung
Entitäts-ID*	Die Entität, für die die Bewertung angefordert wird.
Vorname*	Der Vorname der Person, von der die Bewertung angefordert wird.
Nachname*	Der Nachname der Person, von der die Bewertung angefordert wird.
Titel	Der Titel der Person, von der die Bewertung angefordert wird, z. B. Herr, Frau oder Fräulein.
Kontaktdaten*	Die E-Mail-Adresse oder Telefonnummer der Person, von der die Bewertung angefordert wird.
Vorlagen-ID:	Die Vorlage, die zur Formatierung der Einladung verwendet wird.
Transaktions-ID	Die ID der Transaktion, auf die sich die Einladung bezieht.
Namen der Bewertungslabel	Die Namen der Bewertungslabel, die an die resultierende Bewertung angehängt werden sollen.
Zusätzliche URL-Parameter	Ein JSON-Objekt aus Schlüssel-Wert-Paaren, die an die Review Balancing-URL angehängt werden sollen.

*Pflichtfeld.

Bestätigen Sie, dass Ihre Anwendung alle benötigten Felder bereitstellen kann, bevor Sie Ihre Integration erstellen.

API-Zugriff einrichten

Eine App erstellen

Erstellen Sie eine App in der Entwicklerkonsole und gewähren Sie ihr Zugriff auf die API zur Bewertungseinladung. Für die Abrufen/auflisten-Endpunkte reicht ein Lesezugriff aus. Allerdings ist für das Erstellen, Aktualisieren oder Löschen von Einladungen ein Schreibzugriff erforderlich. Für Ihre App wird ein API-Schlüssel generiert, mit dem Sie auf die Endpunkte für Bewertungseinladungen zugreifen können. Sie sollten diesen API-Schlüssel nicht auf Ihren Seiten für Kund*innen offenlegen. Stellen Sie daher sicher, dass Sie diese App nicht für Anfragen auf Kund*innenseite verwenden.

Eine Einladung erstellen

Eine Anfrage an den Endpunkt „Bewertungseinladungen: Erstellen“ sendet eine Einladung an den von Ihnen angegebenen Kontakt. Das System zur Generierung von Bewertungen sendet Ihnen bei Angabe einer Telefonnummer eine SMS oder bei Angabe einer E-Mail-Adresse eine E-Mail.

Die Antwort enthält zwei Felder, die Sie für spätere Anfragen benötigen:

invitationUid: Eine eindeutige Kennung für die Einladung.
feedbackUrl: Die vollständige URL, die in der Einladung enthalten ist, wobei invitationUid als Anfrageparameter angehängt wird. Wenn Empfänger*innen eine Bewertung über diese URL einreichen, fügen Sie die invitationUid der Anfrage zur Erstellung der Bewertung hinzu, damit das System die Bewertung als Attribut der Einladung zuordnen kann.

Zusätzliche Details zu einer Einladung hinzufügen

Die API unterstützt zwei Möglichkeiten, zusätzlichen Kontext mit einer Einladung zu übermitteln, den Sie dann in der resultierenden Bewertung verwenden können.

Bewertungslabel: Geben Sie Werte in das Feld reviewLabelNames ein. Wenn eine Bewertung mit der passenden invitationUid erstellt wird, werden diese Werte als Label auf die Bewertung angewendet. Wenn man beispielsweise „im Geschäft“ in reviewLabelNames angibt, wird der resultierenden Bewertung das Label „im Geschäft“ zugewiesen.

Zusätzliche URL-Parameter: Geben Sie ein JSON-Objekt mit Schlüssel-Wert-Paaren im additionalURLParameters Feld weiter. Diese werden als Anfrageparameter an die Feedback-URL angehängt, sodass Ihre Sammlungsseite sie lesen und nach Bedarf verwenden kann, einschließlich der Übertragung der Daten an ein externes Attributionssystem, anstatt sie als Label anzuwenden.

Einladungen von einem externen System senden

Wenn Ihr Unternehmen seine eigene E-Mail- oder SMS-Zustellung abwickelt, können Sie einen Einladungseintrag in Yext erstellen, ohne dass Yext ihn erfüllen muss, indem Sie im Anfragetext sendInvitationFromYext = FALSE angeben. Das ist nützlich, wenn:

Sie möchten, dass Yext die verlässliche Quelle für versendete Einladungen bleibt, auch wenn Ihr eigenes System diese zustellt.
Sie Bewertungen nur von Kund*innen akzeptieren möchten, die eine Einladung erhalten haben. Dies erfordert die unten beschriebene zusätzliche Konfiguration.

Einladung per UID zum Einreichen erforderlich

Standardmäßig ermöglicht es eine öffentliche Sammlungsseite jedem, der die URL kennt, eine Bewertung abzugeben, was von vielen Unternehmen gewünscht wird. Um die Einreichungen auf eingeladene Kund*innen zu beschränken, aktivieren Sie in Ihren Kontoeinstellungen Einladungen für Bewertungen aus erster Hand erforderlich. Sobald diese Funktion aktiviert ist, muss jede Anfrage an den Endpunkt „Bewertungseinreichung: Erstellen“ eine gültige invitationUid enthalten, andernfalls wird die Bewertung abgelehnt.

Wenn Sie Einladungen von einem externen System bearbeiten und diese Einstellung ebenfalls benötigen, senden Sie die zurückgegebene feedbackURL selbst an Ihre Kund*innen, nachdem Sie den Einladungseintrag mit sendInvitationFromYext = FALSE erstellt haben.

Einladungen zu einer benutzerdefinierten Sammlungsseite weiterleiten

Standardmäßig leitet die Review Balancing-URL Empfänger*innen auf die Standardsammelseite von Yext weiter. Wenn Einladungen aus erster Hand stattdessen auf eine benutzerdefinierte Sammlungsseite umgeleitet werden sollen:

Navigieren Sie zu Bewertungen > Generierung > Einstellungen.
Aktivieren Sie Sammlungsseite von Bewertungen aus erster Hand überschreiben.
Wählen Sie ein benutzerdefiniertes Feld aus, um Ihre benutzerdefinierten URLs zu speichern, oder erstellen Sie ein solches, falls Sie noch keines haben.
Füllen Sie dieses benutzerdefinierte Feld für jede Entität aus, die Sie umleiten möchten.

Nachdem Sie diese Schritte abgeschlossen haben, wird das Feld Seite für Bewertung aus erster Hand mit dem Wert aus Ihrem benutzerdefinierten Feld ausgefüllt. Die Review Balancing-URL selbst ändert sich nicht. Sie wendet weiterhin die Einstellungen Ihres Ausgleichsalgorithmus an, um zu entscheiden, zu welchem Publisher weitergeleitet wird, und verwendet Ihre eigene URL, wenn zu einer Bewertung aus erster Hand weitergeleitet wird.

Einladungen mit Vorlagen formatieren

Einladungsvorlagen steuern, wie Einladungen den Empfänger*innen angezeigt werden. Yext unterstützt sowohl E-Mail- als auch SMS-Vorlagen, die Sie über die Plattform anpassen können. Die Einrichtungsschritte finden Sie unter Vorlagen zur Generierung von Bewertungen. Wenn Sie bei der Erstellung einer Einladung keine Vorlagen-ID angeben, verwendet Yext die Standardvorlage Ihres Kontos.

CAN-SPAM-Richtlinien befolgen

Der CAN-SPAM Act schreibt vor, dass kommerzielle E-Mails die physische Postanschrift von Absender*innen enthalten müssen. Um Einladungen über das E-Mail-System von Yext zu versenden, geben Sie in Ihren Kontoeinstellungen zur Generierung von Bewertungen eine Marke und eine Adresse ein. Yext fügt diese Informationen automatisch in die Fußzeile von Einladungs-E-Mails ein.

Eine Einladung aktualisieren oder löschen

Verwenden Sie den Endpunkt Aktualisieren, um eine Einladung zu stornieren, die noch nicht gesendet wurde, oder um andere Änderungen vor der Zustellung vorzunehmen. Verwenden Sie den Endpunkt Löschen, um dauerhaft einen Einladungseintrag zu entfernen. Das Löschen einer Einladung hat keinen Einfluss auf den Zustellungsstatus einer bereits versendeten Einladung.

Testen Sie Ihre Integration

Testen Sie Ihre Integration zunächst mit einem Nicht-Produktions- oder Sandbox-Konto, bevor Sie sie flächendeckend einführen. Für automatisierte Tests, wie z. B. eine nächtliche Überprüfung, ob Ihre Datenpipeline Einladungen korrekt versendet, erstellen Sie eine Testeinladung und löschen Sie diese anschließend mit dem Endpunkt Löschen.