La génération d'avis Yext permet aux entreprises d'envoyer des e-mails et des SMS à leurs clients pour les inviter à laisser un avis en utilisant l'URL d'ajustement des avis. Cette URL redirige les utilisateurs vers des sites d'avis tiers et/ou vers votre page de collecte d'avis de première main, en fonction de la répartition que vous avez définie pour l'algorithme d'ajustement des avis. Pour en savoir plus sur l'algorithme d'ajustement des avis, consultez le guide Premiers pas avec Reviews.
Vous pouvez passer par l'API Invitations à laisser un avis pour créer une intégration avec un système externe et gérer les invitations par programmation.
Modèles d'intégration
La plupart des intégrations d'invitation à laisser un avis utilisent l'un des deux modèles suivants.
Push : votre système externe notifie votre application dès qu'un déclencheur se produit, puis votre application crée l'invitation. Voici des exemples de déclencheurs courants avec le modèle Push :
- Un client reçoit un produit et le système de traitement des commandes indique que la livraison est effectuée.
- Un client procède à un achat dans un établissement physique et le système du point de vente indique que la transaction est finalisée.
- Un patient sort d'une consultation et le système de prise de rendez-vous indique que le statut du rendez-vous a été mis à jour.
Pull : votre application récupère régulièrement les données qui déclenchent les invitations au lieu de recevoir une notification en temps réel. Les intégrations Pull sont courantes lorsque le système externe ne prend pas en charge les webhooks pour le déclencheur concerné ou lorsque les données d'invitation sont exportées vers un emplacement FTP à intervalles réguliers.
Points de terminaison de l'API Invitations à laisser un avis
| Point de terminaison | Description | Adresse URL |
|---|---|---|
| Review Invitations: Create | Crée une nouvelle invitation à laisser un avis | POST https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Review Invitations: Get/List | Récupère les invitations à laisser un avis existantes | GET https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Review Invitations: Update | Met à jour une invitation à laisser un avis existante | PUT https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
| Review Invitations: Delete | Supprime une invitation à laisser un avis existante | DELETE https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
Champs d'invitation
Une invitation comprend les champs principaux suivants. Des champs supplémentaires sont requis dans le corps de la demande ; référez-vous à la documentation de l'API pour les consulter en intégralité.
| Champ | Description |
|---|---|
| Identifiant de l'entité* | L'entité pour laquelle l'avis est demandé. |
| Prénom* | Le prénom de la personne à qui l'avis est demandé. |
| Nom* | Le nom de famille de la personne à qui l'avis est demandé. |
| Titre | La civilité de la personne à qui l'avis est demandé, tel que M., Mme, ou Mlle. |
| Coordonnées* | L'adresse e-mail ou le numéro de téléphone de la personne à qui l'avis est demandé. |
| ID de modèle | Le modèle utilisé pour formater l'invitation. |
| ID de transaction | L'identifiant de la transaction à laquelle l'invitation se rapporte. |
| Intitulé des avis | Les intitulés d'avis à apposer à l'avis final. |
| Paramètres URL supplémentaires | Un objet JSON contenant des paires clé-valeur à ajouter à l'URL d'ajustement des avis. |
* Champ obligatoire.
Confirmez que votre application peut fournir tous les champs nécessaires avant de construire votre intégration.
Configurer l'accès à l'API
Créer une application
Créez une application dans la console développeur et accordez-lui l'accès à l'API Invitations à laisser un avis. L'accès en lecture est suffisant pour les points de terminaison Get/List. Cependant, pour créer, mettre à jour ou supprimer des invitations, un accès en écriture est nécessaire. Une clé API sera générée pour permettre à votre application d'accéder aux points de terminaison des invitations à laisser un avis. Vous ne devez pas exposer cette clé API sur vos pages publiques. Aussi, assurez-vous de ne pas utiliser cette application pour les requêtes côté client.
Créer une invitation
Une requête au point de terminaison Review Invitations: Create envoie une invitation au contact que vous spécifiez. Le système de génération d'avis envoie un SMS si vous fournissez un numéro de téléphone ou un e-mail si vous fournissez une adresse e-mail.
La réponse inclut deux champs dont vous aurez besoin pour les demandes ultérieures :
-
invitationUid: un identifiant unique pour l'invitation. -
feedbackUrl: l'URL complète incluse dans l'invitation, avecinvitationUidajouté comme paramètre de requête. Lorsque le destinataire valide un avis depuis cette URL, incluezinvitationUiddans la demande de création d'avis afin que le système puisse attribuer cet avis à l'invitation.
Inclure des informations supplémentaires sur une invitation
L'API propose deux méthodes pour transmettre un contexte supplémentaire avec l'invitation, que vous pouvez ensuite utiliser dans l'avis résultant.
Intitulés d'avis : transmettez les valeurs dans le champ reviewLabelNames. Lorsqu'un avis est créé avec le composant invitationUid correspondant, ces valeurs sont appliquées à l'avis en tant qu'intitulés d'avis. Par exemple, si vous transmettez la valeur « En magasin » dans reviewLabelNames, l'intitulé « En magasin » est appliqué à l'avis créé.
Paramètres URL supplémentaires : transmettez un objet JSON contenant des paires clé-valeur dans le champ additionalURLParameters. Celles-ci sont ajoutées en tant que paramètres de requête à l'URL de commentaires afin que votre page de collecte puisse les lire et les utiliser comme vous le souhaitez, y compris en envoyant les données à un système d'attribution externe plutôt que de les appliquer comme un intitulé.
Envoyer des invitations depuis un système externe
Si votre entreprise gère elle-même la livraison de ses e-mails ou SMS, vous pouvez créer un enregistrement d'invitation dans Yext sans demander à Yext de l'envoyer, en transmettant sendInvitationFromYext = FALSE dans le corps de la requête. C'est utile lorsque :
- Vous voulez que Yext reste le point d'archivage des invitations envoyées, même si votre propre système les distribue.
- Vous souhaitez accepter les avis uniquement des clients ayant reçu une invitation, ce qui nécessite la configuration supplémentaire décrite ci-dessous.
Demander un UID d'invitation pour la validation
Par défaut, une page de collecte publique permet à quiconque disposant de l'URL de laisser un avis, ce que de nombreuses entreprises souhaitent. Pour limiter la participation aux seuls clients invités, activez l'option Nécessite des invitations pour avis de première main dans les paramètres du compte. Lorsqu'elle est activée, chaque requête adressée au point de terminaison Review Submission: Create doit inclure un invitationUid valide, sans quoi l'avis sera rejeté.
Si vous gérez l'envoi des invitations depuis un système externe et que vous avez également besoin de ce paramètre, envoyez vous-même la valeur feedbackURL renvoyée à vos clients après avoir créé l'enregistrement d'invitation avec sendInvitationFromYext = FALSE.
Rediriger les invitations vers une page de collecte personnalisée
Par défaut, l'URL d'ajustement des avis redirige les destinataires vers la page de collecte standard de Yext. Pour rediriger les invitations de première main vers une page de collecte personnalisée :
- Accédez à Avis > Génération > Paramètres.
- Activez Remplacement de la page de collecte d'avis de première main.
- Sélectionnez un champ personnalisé pour contenir vos URL personnalisées, ou créez-en un si vous n'en avez pas encore.
- Renseignez ce champ personnalisé pour chaque entité que vous souhaitez rediriger.
Une fois ces étapes terminées, le champ Page d'avis de première main est renseigné avec la valeur de votre champ personnalisé. L'URL d'ajustement des avis en elle-même ne change pas. Elle applique toujours les paramètres de votre algorithme d'ajustement pour décider vers quel annuaire rediriger et elle utilise votre URL personnalisée lorsqu'elle redirige vers un avis de première main.
Formater les invitations à l'aide de modèles
Les modèles d'invitation contrôlent la façon dont une invitation apparaît au destinataire. Yext propose des modèles d'e-mails et de SMS que vous pouvez personnaliser depuis la plateforme. Consultez Modèles de génération d'avis pour connaître les étapes de configuration. Si vous ne spécifiez pas d'ID de modèle lors de la création d'une invitation, Yext utilise le modèle par défaut de votre compte.
Se conformer à la loi CAN-SPAM
La loi CAN-SPAM exige que les e-mails commerciaux incluent l'adresse postale physique de l'expéditeur. Pour envoyer des invitations via le système de messagerie de Yext, ajoutez un nom de marque et une adresse dans les paramètres du compte de génération d'avis. Yext inclut automatiquement ces informations dans le pied de page des e-mails d'invitation.
Mettre à jour ou supprimer une invitation
Utilisez le point de terminaison Update pour annuler une invitation qui n'a pas encore été envoyée ou pour apporter d'autres modifications avant la livraison. Utilisez le point de terminaison Delete pour supprimer définitivement un enregistrement d'invitation. Supprimer une invitation n'affecte pas le statut de livraison d'une invitation déjà envoyée.
Tester votre intégration
Testez votre intégration sur un compte hors production ou un compte Sandbox avant de la déployer. Pour les tests automatisés, comme une vérification nocturne visant à confirmer que votre pipeline de données envoie correctement les invitations, créez une invitation de test, puis supprimez-la à l'aide du point de terminaison Delete.