Conversations omnicanales avec Vonage, Postmark et Hookdeck

En une seule journée, je peux passer d'un SMS à une conversation avec un ami, de WhatsApp à des mises à jour générales avec les membres de ma famille, de Facebook Messenger à la coordination d'une activité communautaire, et du courrier électronique au travail. Et le canal de communication préféré peut varier en fonction de la personne, du moment de la journée, de la géographie, de la génération et de la culture. Ne serait-ce pas agréable s'il existait une application de communication unique que tout le monde pourrait utiliser et qui fonctionnerait parfaitement sur tous les canaux de communication !

Les conversations omnicanales, qui permettent à une conversation de passer d'un support de communication à l'autre, sont possibles, mais très peu de guides expliquent comment les mettre en pratique. Dans ce tutoriel, nous allons donc voir comment construire une solution OmniText pour permettre une conversation par SMS à l'aide de l'API Vonage Messages API et le courrier électronique à l'aide de l'API Postmark email API. Nous utiliserons également Hookdeck, une plateforme de messagerie asynchrone sans serveur, pour recevoir des webhooks et intégrer Vonage et Postmark via leurs API.

Si vous souhaitez simplement essayer OmniText, vous pouvez récupérer le code ainsi que des instructions simplifiées dans le repo de OmniText sur GitHub.

Présentation d'OmniText

Avant de vous guider pas à pas dans la configuration et l'élaboration de la solution, voici un aperçu du fonctionnement d'OmniText.

Hookdeck a le concept de connexionsqui relient une entrée appelée source à une sortie appelée destination. Pour prendre en charge une conversation croisant le SMS et l'email, nous avons besoin de deux connexions qui :

1. Recevoir un SMS et déclencher un e-mail

2. Recevoir un courriel et déclencher un SMS

Connections in Hookdeck

Pour cette configuration, nous prendrons en charge une seule conversation entre un numéro de téléphone et un courriel. Pour prendre en charge plusieurs conversations avec cette approche, vous devrez créer deux connexions pour chaque conversation. Comme indiqué ci-dessus, il est tout à fait possible de prendre en charge plusieurs conversations, mais cette question n'est pas abordée dans cet article.

Les deux connexions utiliseront les transformations Hookdeck de Hookdeck.

• La connexion inbound-sms transforme la charge utile du webhook SMS de l'API Messages de Vonage en une charge utile utilisée pour envoyer un courriel avec Postmark.

• La connexion inbound-email transforme la charge utile du courriel Postmark entrant en une structure requise par l'API Messages de Vonage pour envoyer un SMS.

Lors de l'envoi d'un courrier électronique, il convient également de noter que si vous pouvez utiliser des sujets de courrier électronique et des sous-adressage pour permettre à une même adresse électronique de participer à plusieurs conversations, le problème est beaucoup plus difficile à résoudre avec les numéros de téléphone et les SMS. Dans cette solution, un numéro de téléphone ne peut donc être associé qu'à une seule conversation.

Conditions préalables

Avant de commencer, ouvrez des comptes gratuits auprès des services requis pour la solution OmniText et récupérez les informations d'identification et les détails supplémentaires :

• VonageVonage : prenez note de votre clé API et de votre secret API. Vous devrez également acheter un numéro de téléphone pour envoyer et recevoir des SMS.

• Marque postale: prenez note du jeton API de votre serveur à partir de Serveurs > {Votre nom de serveur} > Jetons API et l'email entrant à partir de Serveurs > {Votre nom de serveur} > Flux entrant par défaut > Paramètres > Entrant > Email section. Voir la documentation Postmark configuration d'un serveur entrant docs pour plus de détails. N'oubliez pas non plus de "Verify your signature" avec Postmark, ce qui signifie vérifier votre adresse e-mail.

• Pont à crochets: il suffit de créer le compte

Recevoir un SMS et déclencher un e-mail

Commençons par créer une connexion qui soutiendra le flux suivant :

1. Un utilisateur envoie un SMS à votre numéro de téléphone API Vonage.

2. L'API de Vonage déclenche un webhook SMS vers Hookdeck.

3. Hookdeck reçoit les webhooks SMS via une URL source et convertit la charge utile du SMS dans un format qui peut être utilisé pour envoyer un courrier électronique avec Postmark.

4. Hookdeck effectue une requête HTTP vers une URL de destination, le point de terminaison de l'API Postmark pour l'envoi d'un courrier électronique.

5. Un deuxième utilisateur reçoit le courriel

Rendez-vous sur le tableau de bord de Tableau de bord de l'hôtelSélectionnez Connexionset cliquez sur le bouton + Connexion et cliquez sur le bouton + Connexion.

Dans le menu Créer une connexion dans la fenêtre Configurer une sourceappelez la Source inbound-sms.

En Configurer une destinationdéfinir l'option Nom sur outbound-email.

Pour l'option Configurer une destination > URL d'extrémitéutilisez le point de terminaison Point de terminaison de l'API du courriel Postmark, https://api.postmarkapp.com/email.

Agrandir Configurer une destination > Configuration avancéesélectionnez Clé API dans le menu déroulant de l'authentification, définir le Nom du paramètre à X-Postmark-Server-Tokenet utilisez le jeton API de votre serveur Postmark comme valeur pour le paramètre Clé API.

Authentication in Hookdeck for Postmark Request

Dans le menu Définir les règles de connexion cliquez sur Transformer suivi de Créer une nouvelle transformationet vous verrez apparaître l'éditeur de transformation dans le navigateur.

Saisissez le texte suivant dans la zone de texte du code :

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 majeure partie du code est contenue dans une fonction appelée smsToEmail. Voici un aperçu de ce que fait le code :

Tout d'abord, vous remarquerez que le code de transformation récupère un certain nombre de variables environnementales à l'aide de la syntaxe process.env.VARIABLE_NAME. Cela permet d'utiliser les variables d'environnement de Hookdeck variables d'environnement de transformation de Hookdeck qui sont utilisées pour stocker les secrets.

Ouvrez la section Variables et créez les variables suivantes en utilisant vos valeurs de la section Conditions préalables :

• REPLY_TO_EMAIL: L'email de Postmark pour s'assurer que les réponses à l'email vont à Postmark et déclenchent un webhook.

• FROM_EMAIL: Réglez ce paramètre sur le même que REPLY_TO_EMAIL ou l'email avec lequel vous vous êtes inscrit à Postmark. Si vous souhaitez prendre en charge l'envoi d'e-mails à partir d'autres domaines, vous devrez vérifier votre domaine avec Postmark. Cela peut être utile pour aider les clients de messagerie à identifier le contact dans un carnet d'adresses.

• TO_EMAIL: L'adresse électronique de la personne qui reçoit la conversation.

• SUBJECT: L'objet à utiliser dans l'e-mail. Vous pouvez le rendre plus dynamique, si vous le souhaitez.

Une fois les variables d'environnement récupérées dans smsToEmail, a conversationId se voit attribuer une valeur avec un contenu et un format qui garantit que les courriels sont conservés dans le même fil de discussion au sein d'un client de messagerie (pour plus d'informations, voir l'article sur le support du fil de discussion de l'article sur le support du threading de Postmark et cet article sur l'envoi de courriels sur un fil de discussion dans Rails).

Ensuite, la charge utile de l'API de messagerie est construite et affectée à la variable postmarkSendEmailRequest et lui est assignée. Les principaux points dont il faut tenir compte dans cette charge utile sont les suivants :

• TextBody est fixé au texte envoyé dans le SMS

• MessageStream est défini sur outbound pour indiquer à Postmark que le flux transactionnel (sortant) doit être utilisé pour envoyer le courrier électronique.

• Les Headers contiennent un en-tête appelé Message-ID avec la valeur attribuée à partir de l'en-tête conversationId. Comme nous l'avons mentionné, cet en-tête est utilisé pour aider les clients de messagerie à classer les courriels.

request.body se voit attribuer la valeur de la charge utile de l'e-mail Postmark, postmarkSendEmailRequest. Celle-ci est ensuite utilisée dans la demande envoyée à la destination de la connexion, le point de terminaison de l'API Postmark email.

Le fichier transformé request est renvoyé par la fonction et utilisé dans la demande à l'API Postmark, comme défini dans la destination de la connexion. L'appel addHandler demande à Hookdeck d'appeler la fonction smsToEmail chaque fois qu'un transform doit être traité.

Cliquez sur ConfirmerNommez la transformation vonage-sms-to-postmark-emailet cliquez sur Confirmer pour revenir à la page de configuration de la connexion.

En Définir le nom de la connexionentrez sms-to-email. Enfin, cliquez sur +Créer pour créer la connexion.

Successful Connection Created

Copiez l'URL de la source dans la boîte de dialogue qui s'affiche et rendez-vous sur le tableau de bord des API de Vonage.

Dans le tableau de bord de l'API de Vonage, sélectionnez l'onglet Applications à gauche et cliquez sur + Créer une nouvelle application.

Nommez votre application sms-to-email. Dans la section Capacités activez Messageset collez l'URL de votre source Hookdeck dans le champ URL entrante et l URL d'état de l'état. Enfin, cliquez sur Générer une nouvelle application.

Add Hookdeck webhook to Messages API Application

Sur l'écran suivant, vous verrez votre numéro de téléphone Vonage. Reliez-le à l'application que vous venez de créer en cliquant sur Lier.

Link Your Messages API to Your Number

Envoyez ensuite un SMS à votre numéro Vonage.

Test Your First Working OmniText

Retournez au tableau de bord de Hookdeck, et une fois que Hookdeck reçoit le webhook SMS, l'interface utilisateur sera mise à jour pour montrer l'événement webhook reçu comme suit :

Hookdeck Successful Event Fired

Cliquez Voir tous les événements et sélectionnez l'événement dans le tableau pour afficher plus de détails.

Detailed Hookdeck Events Dashboard

Ensuite, vérifiez votre courrier électronique :

Successful SMS to Email

Le tour est joué. La fonctionnalité SMS-to-email est en place.

Recevoir un courriel et déclencher un SMS

Il s'agit maintenant de créer la connexion qui soutient le flux, comme précédemment mais en sens inverse :

1. Un utilisateur envoie un courriel à un courriel associé à Postmark

2. Postmark déclenche un webhook d'email entrant

3. Hookdeck reçoit le webhook de courriel entrant et convertit la charge utile d'un SMS API Voange sortant.

4. Hookdeck fait une demande HTTP à une URL de destination, le point de terminaison de l'API Messages de Vonage, pour envoyer un SMS.

5. Un deuxième utilisateur reçoit le SMS

Comme précédemment, allez dans le tableau de bord de Hookdecket sélectionnez Connexionset cliquez sur le bouton + Connexion et cliquez sur le bouton + Connexion.

Dans le menu Créer une connexion dans la fenêtre Configurer une source donnez à la source le Nom inbound-email.

En Configurer une destinationutilisez le Nom outbound-sms et définissez l URL du point final à l'adresse point de terminaison de l'API Messages de Vonage, https://api.nexmo.com/v1/messages.

Agrandir Configurer une destination > Configuration avancéechoisir Auth de base dans la section Authentification et utilisez votre clé API Vonage comme Nom d'utilisateur et le secret de l'API Vonage comme mot de passe.

Vonage API Authentication in Hookdeck

Dans le menu Définir les règles de connexion cliquez sur Transformer suivi de Créer une nouvelle transformationet, comme précédemment, vous verrez l'éditeur de transformation dans le navigateur.

Copiez et collez le code de transformation suivant dans l'éditeur :

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 majeure partie du code est constituée d'une fonction. Cette fois-ci, elle s'appelle emailToSms.

Comme précédemment, commencez par stocker les variables d'environnement suivantes via la fonction Variables dans le menu déroulant :

• TO_NUMBER: Le numéro de téléphone du destinataire du SMS

• FROM_NUMBER: Le numéro de téléphone Vonage utilisé pour envoyer le SMS

Les numéros de téléphone doivent être formatés avec l'indicatif international du pays, mais sans + ni 00.

Le reste du code fait ce qui suit :

A vonageRequestPayload est créée et contient les données utiles de la demande de l'API Messages. La variable message_type a une valeur de textet la variable channel a une valeur de sms pour indiquer qu'un SMS sera envoyé. La propriété text est le contenu du SMS, et sa valeur est fixée à request.body.StrippedTextReply ou, si elle n'est pas renseignée, la propriété request.body.TextBody. La propriété StrippedTextReply est le corps de l'e-mail d'une réponse qui ne contient que la partie "nouveau message" et non le fil de discussion complet.

Le request.body se voit attribuer la valeur de la variable vonageRequestPayload et la demande renvoyée pour être utilisée dans la demande à la destination de la connexion, le point de terminaison de l'API Messages de Vonage. L'appel addHandler demande à Hookdeck d'appeler l'API emailToSms chaque fois qu'un transform doit être traité.

Cliquez sur ConfirmerNommez la transformation postmark-email-to-vonage-sms et cliquez sur Confirmer pour revenir à la page de configuration de la connexion.

En Définir le nom de la connexionentrez email-to-sms. Enfin, cliquez sur +Créer pour créer la connexion.

Email to SMS Connection Created

Copiez l'URL de la source à partir de la boîte de dialogue, allez dans le tableau de bord de Postmark, et allez dans la section Serveurs > {Votre nom de serveur} > Flux entrant par défaut > Paramètres Paramètres. Descendez jusqu'à la section Crochet web entrant et collez l'URL dans le champ Crochet Web entrant et Enregistrez les modifications.

Postmark Webhook Connecting to Hookdeck

Envoyez un courrier électronique à l'adresse de courrier entrant de Postmark. Vous pouvez le faire en répondant à l'e-mail que vous avez reçu à l'étape précédente.

Successful Programmatic Email Thread Reply

Après avoir envoyé le courriel, retournez au tableau de bord de Hookdeck, et vous verrez que l'événement webhook a été reçu de Postmark.

Hookdeck Successful Email to SMS Event

Cliquez Voir tous les événementssélectionnez l'événement dans le tableau et examinez les détails du webhook Postmark entrant.

Hookdeck Email to SMS Events Detailed

Vérifiez vos messages SMS pour voir le corps de l'e-mail dans le message SMS :

Successful Email to SMS

Vous pouvez également essayer de répondre à nouveau à partir du SMS pour vous assurer que la conversation est bien reprise dans votre client de messagerie :

Successful SMS reply to Email Thread

Vous devriez donc voir le fil de discussion dans votre courrier électronique :

Successful Threading in Email From SMS

Conclusion

Dans ce tutoriel, nous avons abordé la création d'une connexion dans Hookdeck qui reçoit un webhook SMS de l'API Messages de Vonage, la transformation de la charge utile en une demande API de courrier électronique Postmark et l'envoi du corps du SMS en tant que corps d'un courrier électronique. Nous avons ensuite créé une deuxième connexion Hookdeck qui reçoit un webhook de courrier électronique Postmark. Nous transformons la charge utile en une charge utile de demande pour l'API Messages de Vonage et envoyons le corps du courriel en tant que contenu d'un SMS. Dans tous les cas, les informations d'identification de l'API sont stockées en toute sécurité dans Hookdeck.

Vous disposez ainsi d'une solution de conversation omni-canal, qui fait le lien entre le SMS et le courrier électronique.

Le repo GitHub OmniText GitHub repo contient le code qui montre comment configurer les connexions dans Hookdeck. N'hésitez pas à l'essayer comme moyen alternatif de travailler avec Hookdeck.

Cet article décrit l'utilisation du tableau de bord de Hookdeck pour réaliser la fonctionnalité nécessaire à la prise en charge d'une conversation unique entre un numéro de téléphone et un courriel prédéfinis. Cependant, tout ce que nous avons fait est réalisable en utilisant l Hookdeck API. La création programmatique de nouvelles connexions est une approche potentielle que vous pourriez adopter pour prendre en charge des conversations multiples, ou vous pourriez stocker une recherche bidirectionnelle email-SMS sur une sorte d'événement d'enregistrement de la conversation.

Si vous êtes à la recherche d'une solution à code réduit ou sans code, jetez un coup d'œil à Vonage API Studio.

Voici quelques autres choses que vous pouvez essayer avec les technologies utilisées dans cet article :

• Ajout de vérification du webhook aux webhooks Postmark et Vonage Messages entrants

• Utilisation de l'interface CLI de Hookdeck pour recevoir les webhooks dans votre environnement de développement local (similaire à ce pour quoi ngrok est le plus connu)

• Création d'une 2ème, 3ème et nème conversation. N'hésitez pas à discuter des solutions potentielles en créant un problème dans le repo OmniText.

• Ajout d'un soutien pour d'autres canaux de messagerie tels que WhatsApp, Facebook Messenger et Viber à l'aide de l'API Messages de Vonage. Vonage Messages API

Quoi que vous décidiez de faire ensuite, nous voulons le savoir ! Rejoignez-nous sur le Communauté des développeurs de Vonage Slack ou envoyez-nous un message sur X, anciennement connu sous le nom de Twitter.