La generación de comentarios de Yext permite a las empresas enviar invitaciones por correo electrónico y SMS a sus clientes para que soliciten un comentario mediante la URL de Review Balancing. Esta URL dirige a los usuarios a sitios de comentarios de terceros o a su página de recopilación de comentarios en primera persona, dependiendo de la distribución que establezca para el algoritmo de Review Balancing. Puede obtener más información sobre el algoritmo de Review Balancing en la guía Cómo empezar con los comentarios.
Puede usar la API de invitaciones de comentarios para integrar un sistema externo y gestionar las invitaciones de forma programática.
Patrones de integración
La mayoría de las integraciones de invitaciones de comentarios emplean uno de dos patrones.
Push: su sistema externo notifica a su aplicación tan pronto como se activa un desencadenante, y su aplicación crea la invitación. Los factores desencadenantes más comunes incluyen:
- Un cliente recibe un producto y el sistema logístico indica que la entrega se ha completado.
- Un cliente completa una compra en un local físico, y el sistema de punto de venta señala que la transacción se ha completado.
- Un paciente completa una visita y el sistema de programación indica que el estado de la cita se ha actualizado.
Pull: su aplicación obtiene periódicamente datos que activan invitaciones en lugar de recibir una notificación en tiempo real. Las integraciones Pull son comunes cuando el sistema externo no es compatible con webhooks para el desencadenante correspondiente, o cuando los datos de invitación se exportan a una ubicación de FTP programada.
Puntos finales de la API de invitaciones de comentarios
| Punto final | Descripción | URL |
|---|---|---|
| Invitaciones de comentarios: Create | Crea una nueva invitación de comentario. | POST https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Invitaciones de comentarios: Get/List | Obtiene las invitaciones a dejar comentarios existentes. | GET https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites |
| Invitaciones de comentarios: Update | Actualiza una invitación de comentario. | PUT https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
| Invitaciones de comentarios: Delete | Elimina una invitación de comentario existente. | ELIMINAR https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid} |
Campos de invitación
La invitación incluye los siguientes campos principales. Se requieren campos adicionales en el cuerpo de la solicitud; consulte la documentación de la API para obtener una referencia completa.
| Campo | Descripción |
|---|---|
| ID de entidad* | La entidad para la que se solicita el comentario. |
| Nombre * | El nombre de pila de la persona a la que se solicita el comentario. |
| Apellido * | El apellido de la persona a la que se solicita el comentario. |
| Título | El título de la persona a la que se solicita el comentario, como Sr., Sra. o Srta. |
| Contacto* | La dirección de correo electrónico o el número de teléfono de la persona a la que se le solicita el comentario. |
| ID de la plantilla: | La plantilla utilizada para formatear la invitación. |
| ID de la transacción | El ID de la transacción a la que se refiere la invitación. |
| Nombres de etiquetas de comentarios | Los nombres de las etiquetas de comentarios para adjuntar al comentario resultante. |
| Parámetros adicionales de URL | Un objeto JSON de pares clave-valor para añadirlo a la URL de Review Balancing. |
*Campo obligatorio.
Confirme que su solicitud puede proporcionar todos los campos que necesita antes de construir su integración.
Configurar el acceso a la API
Crear una aplicación
Cree una aplicación en la consola de desarrolladores y de acceso a la API de las invitaciones para comentarios. El acceso de lectura es suficiente para los puntos finales Get/List. Sin embargo, para crear, actualizar o eliminar invitaciones, se requiere acceso de escritura. Se generará una clave de API para que su aplicación acceda a los puntos finales de las invitaciones para comentarios. No querrá mostrar la clave de API en sus páginas del lado del cliente, así que asegúrese de no utilizar esta aplicación para ninguna solicitud del lado del cliente.
Crear una invitación
Al enviar una solicitud al punto final Invitaciones de comentarios: Create, se envía una invitación al contacto que se especifique. El sistema de generación de comentarios enviará un SMS si proporciona un número de teléfono o un correo electrónico si proporciona una dirección de correo electrónico.
La respuesta incluye dos campos que necesitará para futuras solicitudes:
-
invitationUid: un identificador único para la invitación. -
feedbackUrl: la URL completa incluida en la invitación, con elinvitationUidañadido como parámetro de consulta. Cuando el destinatario envíe un comentario desde esta URL, incluya elinvitationUiden la solicitud de creación del comentario para que el sistema pueda atribuir el comentario a la invitación.
Incluir detalles adicionales en una invitación
La API admite dos formas de incluir información adicional junto con una invitación, que luego podrás utilizar en el comentario resultante.
Etiquetas de comentarios: introduce los valores en el campo reviewLabelNames. Cuando se crea un comentario con el invitationUid correspondiente, esos valores se aplican al comentario como etiquetas de comentarios. Por ejemplo, al introducir «In-Store» en reviewLabelNames se aplica la etiqueta «In-Store» al comentario resultante.
Parámetros adicionales de URL: introduce un objeto JSON de pares clave-valor en el campo additionalURLParameters. Estos se añaden como parámetros de consulta a la URL de comentarios, de modo que su página de recopilación pueda leerlos y utilizarlos como necesite, lo que incluye enviar los datos a un sistema de atribución externo en lugar de aplicarlos como etiqueta.
Enviar invitaciones desde un sistema externo
Si su empresa gestiona sus propios envíos de correo electrónico o SMS, puede crear un registro de invitación en Yext sin que Yext lo procese introduciendo sendInvitationFromYext = FALSE en el cuerpo de la solicitud. Esto es útil cuando:
- Quiere que Yext siga siendo la fuente de verdad para las invitaciones enviadas, aunque su propio sistema las entregue.
- Solo quiere aceptar comentarios de clientes que hayan recibido una invitación, lo que requiere la configuración adicional que se describe a continuación.
Requiere un UID de invitación para el envío
Por defecto, una página de recopilación pública permite a cualquier persona con la URL dejar un comentario, algo que muchas empresas desean. Para restringir las publicaciones solo a los clientes invitados, active Exigir invitaciones para los comentarios en primera persona en la configuración de su cuenta. Una vez habilitado, cada solicitud al punto final Envío de comentarios: Create debe incluir un invitationUid válido, o el comentario será rechazado.
Si está gestionando invitaciones desde un sistema externo y también necesita esta configuración, envíe usted mismo la feedbackURL devuelta a sus clientes después de crear el registro de la invitación con sendInvitationFromYext = FALSE.
Redirigir las invitaciones a una página de recopilación personalizada
Por defecto, la URL de Review Balancing dirige a los destinatarios a la página de recopilación estándar de Yext. Para redirigir las invitaciones de primera persona a una página de recopilación personalizada en su lugar:
- Vaya a Comentarios > Generación > Configuración.
- Habilite Reemplazar página de recopilación de comentarios en primera persona.
- Seleccione un campo personalizado para guardar sus URL personalizadas, o cree uno si aún no lo ha hecho.
- Rellene ese campo personalizado para cada entidad que quiera redirigir.
Una vez completados estos pasos, el campo Página de comentarios en primera persona se rellenará con el valor de su campo personalizado. La URL de Review Balancing en sí misma no cambia; sigue aplicando la configuración del algoritmo de Balancing para decidir a qué editor enviar y utiliza su URL personalizada cuando se dirige a un comentario en primera persona.
Formatear invitaciones con plantillas
Las plantillas de invitación controlan cómo aparece una invitación para el destinatario. Yext admite plantillas de correo electrónico y SMS que usted puede personalizar desde la plataforma. Consulte las plantillas de generación de comentarios para ver los pasos de configuración. Si no especifica un ID de plantilla al crear una invitación, Yext usa la plantilla predeterminada de su cuenta.
Cumplir la ley CAN-SPAM
La Ley CAN-SPAM exige que los correos electrónicos comerciales incluyan la dirección postal física del remitente. Para enviar invitaciones a través del sistema de correo electrónico de Yext, añada un nombre de marca y una dirección en la configuración de su cuenta de generación de comentarios. Yext incluye esta información automáticamente en el pie de página de los correos electrónicos de invitación.
Actualizar o eliminar una invitación
Use el punto final Actualizar para cancelar una invitación que aún no se ha enviado, o para hacer otros cambios antes de la entrega. Use el punto final Eliminar para eliminar permanentemente un registro de invitación. Eliminar una invitación no afecta al estado de entrega de una invitación que ya se ha enviado.
Probar la integración
Pruebe su integración con una cuenta que no sea de producción o en un entorno de pruebas antes de implementarla. Para las pruebas automatizadas, como una comprobación nocturna de que su pipeline de datos está enviando las invitaciones correctamente, cree una invitación de prueba y luego elimínela usando el punto final Eliminar.