Conversaciones omnicanal con Vonage, Postmark y Hookdeck

En un solo día, puedo saltar entre SMS para una conversación con un amigo, WhatsApp para actualizaciones generales con miembros de la familia, Facebook Messenger para coordinar una actividad comunitaria y el correo electrónico para el trabajo. Y el canal de comunicación preferido puede variar según la persona, la hora del día, la geografía, la generación y la cultura. ¿No estaría bien que hubiera una aplicación de comunicación que todo el mundo pudiera utilizar y que funcionara bien en todos los canales de comunicación?

Las conversaciones omnichannel - permitir que una conversación cruce los medios de comunicación - es una posibilidad, pero hay muy pocas guías que demuestren cómo ponerlo en práctica. Por lo tanto, en este tutorial, veremos cómo crear una solución OmniText para permitir una conversación a través de SMS usando la Messages API y correo electrónico mediante API de correo electrónico de Postmark. También utilizaremos Hookdeckuna plataforma de mensajería asíncrona sin servidor, para recibir webhooks e integrar Vonage y Postmark a través de sus API.

Si sólo desea probar OmniText, puede obtener el código junto con instrucciones simplificadas en el repositorio de OmniText en GitHub.

Visión general de OmniText

Antes de seguir una guía paso a paso para configurar y crear la solución, a continuación le ofrecemos una descripción general del funcionamiento de OmniText.

Hookdeck tiene el concepto de conexionesque conectan una entrada conocida como fuente a una salida llamada destino. Para mantener una conversación cruzando SMS y correo electrónico, necesitamos dos conexiones que:

1. Recibir un SMS y enviar un correo electrónico

2. Recibir un correo electrónico y activar un SMS

Connections in Hookdeck

Para esta configuración, admitiremos una única conversación entre un número de teléfono y un correo electrónico. Para soportar múltiples conversaciones con este enfoque, necesitarías crear dos conexiones para cada conversación. Como se mencionó anteriormente, el apoyo a múltiples conversaciones es totalmente posible, pero no está cubierto en este artículo.

Ambas conexiones harán uso de Hookdeck transformaciones.

• La conexión inbound-sms transforma la carga útil entrante del webhook SMS de la API de Messages de Vonage en una carga útil utilizada para enviar un correo electrónico con Postmark.

• La conexión inbound-email transforma la carga útil del correo electrónico entrante de Postmark en una estructura requerida por la API de Messages de Vonage para enviar un SMS

Al enviar un correo electrónico, también hay que tener en cuenta que, aunque se pueden utilizar asuntos y subdirecciones para que una misma dirección de correo electrónico forme parte de varias conversaciones, esto es mucho más difícil con los números de teléfono y los mensajes SMS. Por eso, en esta solución, un número de teléfono sólo puede asociarse a una única conversación.

Requisitos previos

Antes de empezar, regístrese para obtener cuentas gratuitas con los servicios necesarios para la solución OmniText y obtenga las credenciales respectivas y detalles adicionales:

• Vonage: toma nota de tu clave API y tu secreto API. También necesitarás comprar un número de teléfono para enviar y recibir mensajes SMS.

• Matasellos: tome nota del token API de su servidor desde Servidores > {Nombre de su servidor} > Tokens API y el correo electrónico entrante desde Servidores > {Nombre de su servidor} > Flujo de entrada predeterminado > Configuración > Entrada > Correo electrónico sección. Consulte los documentos configuración de un servidor de entrada docs para obtener más información. Además, recuerde "Verify your signature" con Postmark, lo que significa verificar su dirección de correo electrónico.

• Cubierta de ganchos: acaba de crear la Account

Recibir un SMS y activar un correo electrónico

Empecemos por crear una conexión que soporte el siguiente flujo:

1. Un usuario envía un SMS a tu número de teléfono API de Vonage

2. La API de Vonage activa un webhook de SMS para Hookdeck

3. Hookdeck recibe los webhooks de SMS a través de una URL de origen y convierte la carga útil del SMS a un formato que se puede utilizar para enviar un correo electrónico con Postmark

4. Hookdeck realiza una solicitud HTTP a una URL de destino, el punto final de la API de correo electrónico de Postmark, para enviar un correo electrónico

5. Un segundo usuario recibe el correo electrónico

Vaya al Panel de controlseleccione Conexionesy haz clic en el botón + Conexión .

En el menú Crear conexión en la sección Configurar una fuentellame a la Fuente inbound-sms.

En Configurar un destinoconfigure el Nombre a outbound-email.

Para Configurar un destino > URL de punto finalutilice el Punto final de la API de correo electrónico del matasellos, https://api.postmarkapp.com/email.

Ampliar Configurar un destino > Configuración avanzadaseleccione Clave API en el menú desplegable de autenticación, establezca el Nombre del parámetro en X-Postmark-Server-Tokeny utilice el token de API del servidor de Postmark como valor de Clave de API.

Authentication in Hookdeck for Postmark Request

En la sección Establecer reglas de conexión haga clic en Transformar seguido de Crear nueva transformacióny verá el editor de transformaciones del navegador.

Introduzca lo siguiente en el área de texto de código:

const smsToEmail = (request, context) => {
 const replyToEmail = process.env.REPLY_TO_EMAIL;
 const fromEmail = process.env.FROM_EMAIL;
 const toEmail = process.env.TO_EMAIL;
 const subject = process.env.SUBJECT;


 const domain = toEmail ? toEmail.replace(/.*@/, "") : "example.com";
 const conversationId = `<omnitext/conversation/1@${domain}>`;


 const postmarkSendEmailRequest = {
   From: fromEmail,
   To: toEmail,
   ReplyTo: replyToEmail,
   Subject: subject,
   TextBody: request.body.text,
   MessageStream: "outbound",


   Headers: [
     {
       Name: "Message-ID",
       Value: conversationId,
     },
   ],
 };


 request.body = postmarkSendEmailRequest;


 return request;
};


addHandler("transform", smsToEmail);

La mayor parte del código se encuentra en una función denominada smsToEmail. He aquí un recorrido por lo que hace el código:

En primer lugar, observará que el código de transformación recupera una serie de variables de entorno utilizando la sintaxis process.env.VARIABLE_NAME. Esto hace uso de las variables de entorno de transformación que se utilizan para almacenar secretos.

Abrir las Variables y cree las siguientes variables utilizando los valores de la sección Requisitos previos:

• REPLY_TO_EMAIL: El correo electrónico de Postmark para garantizar que las respuestas de correo electrónico vayan a Postmark y activen un webhook.

• FROM_EMAIL: Establézcalo como REPLY_TO_EMAIL o el correo electrónico con el que se registró en Postmark. Si desea admitir el envío de correo electrónico desde otros dominios, deberá verificar su dominio con Postmark. Esto puede ser útil para ayudar a los clientes de correo electrónico a identificar el contacto en una libreta de direcciones.

• TO_EMAIL: La dirección de correo electrónico de la persona que recibe parte de la conversación.

• SUBJECT: El asunto que se utilizará en el correo electrónico. Si lo desea, puede hacerlo más dinámico.

Una vez recuperadas las variables de entorno dentro de smsToEmail, a conversationId se le asigna un valor con un contenido y un formato que garantiza que los correos electrónicos se mantengan en el mismo hilo dentro de un cliente de correo electrónico (para obtener más información, consulte el artículo Postmark threading support y este post sobre envío de correos electrónicos que se enhebran en Rails).

A continuación, se crea la carga útil de la API de correo electrónico y se asigna a la variable postmarkSendEmailRequest variable. Los principales puntos a tener en cuenta dentro de esta carga útil son:

• TextBody se establece en el texto enviado dentro del SMS

• MessageStream se establece en outbound para indicar a Postmark que debe utilizar el flujo transaccional (saliente) para enviar el correo electrónico

• La página Headers contienen una cabecera llamada Message-ID con el valor asignado desde la cabecera conversationId. Como ya se ha mencionado, se utiliza para ayudar a los clientes de correo electrónico a enhebrar los mensajes.

request.body se le asigna el valor de la carga útil del correo electrónico Postmark, postmarkSendEmailRequest. A continuación, se utiliza en la solicitud posterior enviada al destino de la conexión, el punto final de la API de correo electrónico de Postmark.

El transformado request se devuelve desde la función y se utiliza dentro de la solicitud a la API de Postmark, tal y como se establece en el destino de la conexión. La llamada a addHandler indica a Hookdeck que llame a la función smsToEmail cada vez que transform deba ser gestionado.

Haga clic en Confirmarnombre la transformación vonage-sms-to-postmark-emaily haga clic en Confirme para volver a la página de configuración de la conexión.

En Establecer nombre de conexiónintroduzca sms-to-email. Por último, haga clic en +Crear para crear la conexión.

Successful Connection Created

Copia la URL de origen del cuadro de diálogo que aparece y dirígete al panel de API de Vonage.

En el panel de control de la API de Vonage, seleccione la opción Applications a la izquierda y haz clic en + Crear una nueva aplicación.

Nombre de su aplicación sms-to-email. En la sección Capacidades habilite Mensajesy pegue su URL de origen de Hookdeck en el campo URL de entrada y URL de estado de estado. Finalmente, haz clic en Generar nueva aplicación.

Add Hookdeck webhook to Messages API Application

En la siguiente pantalla, verás tu número de teléfono de Vonage. Enlázalo a la aplicación que acabas de crear haciendo clic en Vincular.

Link Your Messages API to Your Number

Ahora, envía un SMS a tu número de Vonage.

Test Your First Working OmniText

Vuelve al panel de control de Hookdeck, y una vez que Hookdeck reciba el webhook SMS, la interfaz de usuario se actualizará para mostrar el evento webhook recibido de la siguiente manera:

Hookdeck Successful Event Fired

Haga clic en Ver todos los eventos y seleccione el evento en la tabla para ver más detalles.

Detailed Hookdeck Events Dashboard

A continuación, comprueba tu correo electrónico:

Successful SMS to Email

Ya está. La función de SMS a correo electrónico ya está instalada.

Recibir un correo electrónico y activar un SMS

Ahora a crear la conexión que soporta el flujo, igual que antes pero a la inversa:

1. Un usuario envía un correo electrónico a un correo electrónico asociado a Postmark

2. El matasellos activa un webhook de correo electrónico entrante

3. Hookdeck recibe el webhook de correo electrónico entrante y convierte la carga útil de un SMS saliente de la API de Voange

4. Hookdeck realiza una solicitud HTTP a una URL de destino, el punto final de Messages API de Vonage, para enviar un SMS

5. Un segundo usuario recibe el SMS

Como antes, vaya al Panel de control de Hookdeckseleccione Conexionesy haz clic en el botón + Conexión .

En el menú Crear conexión en la sección Configurar una fuente indique a la Fuente el Nombre inbound-email.

En Configurar un destinoutilice el campo Nombre outbound-sms y establezca la URL del punto final en el punto final de la API de Messages API de Vonage, https://api.nexmo.com/v1/messages.

Ampliar Configurar un destino > Configuración avanzadaseleccione Autenticación básica en la sección Autenticación y utiliza tu clave API de Vonage como nombre de usuario y el secreto de la API de Vonage como contraseña.

Vonage API Authentication in Hookdeck

En la sección Establecer reglas de conexión haga clic en Transformar seguido de Crear nueva transformacióny, como antes, verá el editor de transformaciones del navegador.

Copie y pegue el siguiente código de transformación en el editor:

const emailToSms = (request, context) => {
 const toNumber = process.env.TO_NUMBER;
 const fromNumber = process.env.FROM_NUMBER;


 const vonageRequestPayload = {
   message_type: "text",
   text: request.body.StrippedTextReply || request.body.TextBody,
   to: toNumber,
   from: fromNumber,
   channel: "sms",
 };
 request.body = vonageRequestPayload;


 return request;
};


addHandler("transform", emailToSms);

La mayor parte del código es con una función. Esta vez llamada emailToSms.

Como antes, comience almacenando las siguientes variables de entorno a través de la variable Variables desplegable:

• TO_NUMBER: Número de teléfono del destinatario del SMS

• FROM_NUMBER: El número de teléfono de Vonage utilizado para enviar el SMS

Los Numbers deben estar formateados con el código internacional del país, pero sin + ni 00.

El resto del código hace lo siguiente:

A vonageRequestPayload que contiene la carga útil de la solicitud de la API de Messages. La variable message_type tiene un valor de texty la variable channel tiene un valor de sms para indicar que se enviará un mensaje SMS. La propiedad text es el contenido del SMS, y el valor se establece en request.body.StrippedTextReply o, si no se rellena, la propiedad request.body.TextBody. El StrippedTextReply es el cuerpo de correo electrónico de una respuesta con sólo la parte del mensaje nuevo y no el hilo de correo electrónico completo.

En request.body se le asigna el valor de la variable vonageRequestPayload y se devuelve la solicitud que se utilizará en la solicitud al destino de la conexión, el punto final de la API de Messages API de Vonage. La llamada a addHandler indica a Hookdeck que llame a la función emailToSms cada vez que se deba transform debe ser manejado.

Haga clic en Confirmarnombre la transformación postmark-email-to-vonage-sms y haga clic en Confirme para volver a la página de configuración de la conexión.

En Establecer nombre de conexiónintroduzca email-to-sms. Por último, haga clic en +Crear para crear la conexión.

Email to SMS Connection Created

Copie la URL de origen del cuadro de diálogo, diríjase al panel de control de Postmark y vaya a la sección Servidores > {Nombre de su servidor} > Flujo entrante predeterminado > Configuración Configuración. Desplácese hasta la sección Gancho web entrante y pegue la URL en el campo Webhook de entrada y Guarde los cambios.

Postmark Webhook Connecting to Hookdeck

Envíe un correo electrónico a la dirección de correo electrónico de entrada del matasellos. Puede hacerlo respondiendo al correo electrónico que recibió en el paso anterior.

Successful Programmatic Email Thread Reply

Después de enviar el correo electrónico, vuelve al panel de control de Hookdeck y verás que se ha recibido el evento webhook de Postmark.

Hookdeck Successful Email to SMS Event

Haga clic en Ver todos los eventosseleccione el evento en la tabla e inspeccione los detalles del webhook Postmark entrante.

Hookdeck Email to SMS Events Detailed

Comprueba tus mensajes SMS para ver el cuerpo del correo electrónico dentro del mensaje SMS:

Successful Email to SMS

También puedes probar a responder de nuevo desde SMS para asegurarte de que la conversación se enlaza en tu cliente de correo electrónico:

Successful SMS reply to Email Thread

Así que en tu correo electrónico deberías ver el hilo:

Successful Threading in Email From SMS

Conclusión

En este tutorial, cubrimos la creación de una conexión en Hookdeck que recibe un webhook de SMS de la API de Messages de Vonage, la transformación de la carga útil en una solicitud de API de correo electrónico de Postmark y el envío del cuerpo del SMS como cuerpo de un correo electrónico. Luego creamos una segunda conexión Hookdeck que recibe un webhook de correo electrónico de Postmark. Transformamos la carga útil en una carga útil de solicitud para la API de Messages API de Vonage y enviamos el cuerpo del correo electrónico como el contenido de un mensaje SMS. En todos los casos, las credenciales de la API se almacenan de manera segura dentro de Hookdeck.

Y con eso, ya ha creado una solución de conversación omnicanal, que une los SMS y el correo electrónico.

El OmniText GitHub repo contiene el código que muestra cómo configurar las conexiones dentro de Hookdeck. Siéntase libre de intentarlo como una forma alternativa de trabajar con Hookdeck.

Este artículo explica cómo utilizar el panel de control de Hookdeck para conseguir la funcionalidad necesaria para mantener una única conversación entre un número de teléfono predefinido y un correo electrónico. Sin embargo, todo lo que hicimos se puede lograr utilizando la API de Hookdeck. La creación programática de nuevas conexiones es un enfoque potencial que podrías tomar para soportar múltiples conversaciones, o podrías almacenar una búsqueda bidireccional de correo electrónico a SMS en algún tipo de evento de registro de conversación.

Si buscas una solución de bajo código/sin código, echa un vistazo a Vonage API Studio.

Otras cosas que también puedes probar con las tecnologías utilizadas en este artículo son:

• Añadir verificación de webhook a los webhooks entrantes de Postmark y Vonage Messages

• Uso de la Hookdeck CLI para recibir los webhooks en su entorno de desarrollo local (similar a lo que ngrok es más conocido)

• Crear una 2ª, 3ª y enésima conversación. Siéntete libre de discutir posibles soluciones para esto creando un problema en el repositorio de OmniText.

• Agregar compatibilidad con otros canales de mensajería como WhatsApp, Facebook Messenger y Viber mediante la Mensajes API de Vonage

Sea lo que sea lo próximo que decida hacer, ¡queremos saberlo! Únete a nosotros en Slack de la comunidad de desarrolladores de Vonage o envíanos un mensaje en X, antes conocido como Twitter.