Passer des appels téléphoniques avec Microsoft Excel et le SDK Open ContactPad de Vonage

Introduction

Sur cette page, j'expliquerai comment j'ai construit une intégration VBC fonctionnelle avec une plateforme tierce en peu de temps, en utilisant le nouveau Vonage Integration Integration Platform. Tout d'abord, voici une Video qui démontre les fonctionnalités disponibles de l'intégration.

Applications sélectionnées - Microsoft Excel Online

J'ai sélectionné Microsoft Excel Online car j'avais récemment lu que Microsoft avait publié une API JavaScript pour Excel. De nombreuses personnes utilisent ce programme pour travailler avec des feuilles de calcul et j'ai trouvé qu'il s'agissait d'un moyen raisonnablement simple de traiter les données. Microsoft Excel permet des intégrations par le biais de Office Add-Ins. L'un des compléments les plus intéressants est Script Labqui permet aux développeurs d'expérimenter la création de compléments. L'objectif de ce guide pratique est d'ajouter le code dans Script Lab en utilisant les fonctions JavaScript d'Excel et de Vonage, puis de publier le résultat dans un fichier Gist GitHub. Pour aller plus loin, le lecteur peut être intéressé par les points suivants Publication de compléments Office.

Suivre l'évolution de Microsoft Excel Online

Pour tirer le meilleur parti de ce mode d'emploi, il est recommandé d'installer le complément Office de Script Lab et d'importer le Gist depuis Github :

Le Gist contient le code source complet que vous pouvez adapter à votre projet. Les exemples ci-dessous sont parfois très spécifiques et n'incluent pas tout ce dont vous avez besoin pour faire fonctionner une certaine fonction.

Mise en route du Vonage Open ContactPad

Le SDK SDK Open ContactPad de Vonage est une boîte à outils de développement logiciel JavaScript qui permet aux développeurs d'intégrer un système de communications unifiées (CU) de Vonage de Vonage dans une application Web. Bien qu'il soit nécessaire d'ouvrir une session à l'aide d'un Vonage Business Communications pour l'utiliser, vous pouvez développer avec le SDK sans avoir besoin d'utilisateurs API ou d'inscriptions supplémentaires. Il s'agit donc d'un cadre d'intégration très léger pour les développeurs qui souhaitent intégrer des clients de communication dans leurs applications.

Pourquoi Microsoft Excel en ligne et non une application PC / Mac ?

Il est important de noter que le produit Vonage Open ContactPad SDK est destiné à être intégré dans des applications Web et qu'il fonctionne mieux lorsque le développeur a le contrôle total de l'espace dans lequel il est intégré. Il y a une note au bas de la page page de démarrage qui précise ce point.

Mise en place de Script Lab et premières lignes de code

Lorsque vous installez Script Lab dans Excel, il crée un élément de menu Script Lab à droite de l'élément de menu Aide. Cliquez sur son onglet, vous verrez alors 3 boutons qui vous aideront à travailler avec Script Lab - Code, Exécuter, et Fonctions. Ensuite, cliquez sur Code, une fenêtre apparaît dans l'interface Excel avec une fenêtre de type VisualStudio qui contiendra votre code. Tant que vous n'effacez pas le cache de votre navigateur, votre code Script Lab est conservé. Si vous préférez une plus grande permanence, vous utiliserez l'option Partager pour enregistrer votre code en tant que gist dans GitHub. Dans mes aventures, j'ai fini par créer beaucoup de gists privées. Si je travaillais sur un véritable projet d'intégration, je transférerais probablement mon code vers Visual Studio Code et travaillerais avec un contrôle de version plus précis.

Une fois que j'ai compris le fonctionnement de Script Lab, j'ai commencé par la section HTML où je savais que je voulais intégrer mon composeur. Pour suivre, jetez un coup d'oeil aux instructions ici pour charger l'Open ContactPad. Cela inclut un exemple en direct de la façon de procéder en utilisant Plunker.

Dans mon cas, je voulais fournir un <div> afin que mon application apparaisse dans l'interface complète du composeur et non comme un point mobile sur la page. J'ai défini le fournisseur de données comme uc afin de charger le composeur de communications unifiées.

<div class="vonage-dialer-container"></div>
<script data-provider="uc" data-autoload="false" src="https://apps.gunify.vonage.com/cti/common/vonage.dialer.sdk.js">
</script>

Ce qui est étonnant, c'est que vous pouvez ARRÊTER ICI, exécuter le code et avoir un composeur intégré dans Microsoft Excel Online ! Cependant, les développeurs peuvent faire beaucoup plus pour personnaliser l'expérience.

Exploration de l'API Excel - Mise en place de l'échantillon de données

Alors, pourquoi créer des échantillons de données ? Je voulais donner aux utilisateurs des exemples de format et d'emplacement des données dans la feuille de calcul afin que le code sache où les trouver. Je voulais une zone cliquable pour déclencher un appel téléphonique pour chaque "contact" (ligne) et définir un emplacement pour un numéro de téléphone. J'ai commencé avec le code HTML de l'application dans Script Lab et j'ai ajouté un bouton qui remplirait les données dans la section souhaitée de la feuille de calcul. Si vous appuyez plusieurs fois sur ce bouton, il remplacera simplement ce qui se trouve sur la feuille.

<center><button onclick="populateSampleData()">Populate Sample Data</button></center>

L'étape suivante consiste à implémenter la fonction populateSampleData() en JavaScript. Heureusement, la documentation Microsoft Excel JavaScript API documentation contient quelques exemples.

function populateSampleData() {
 return Excel.run(function(context) {
   var worksheet = context.workbook.worksheets.getItem("Sheet1");
 
   var data = [
     ["Company", "Contact Last", "Contact First", "Number", ""],
     ["Widget Zone", "Anderson", "Wendy", "555-555-5555", "Dial"],
     ["Widgets Galore", "Burns", "Ryan", "555-555-5555", "Dial"],
     ["Widgets Emporium", "Johnson", "Amanda", "555-555-5555", "Dial"]
   ];
 
   var range = worksheet.getRange("A2:E5");
   range.values = data;
   range.format.autofitColumns();
 
   return context.sync().then(function() {});
 }).catch(errorHandlerFunction);
}

Dans un premier temps, vous sélectionnez la première feuille de calcul qui, dans un fichier Excel vierge, est normalement appelée "Feuille1". Créez ensuite un objet contenant les données de la feuille. Ensuite, définissez la plage pour couvrir le nombre de cellules que les données occuperont et définissez les valeurs de la plage pour l'objet de données. L'ajustement automatique des colonnes rend l'apparence un peu plus nette.

J'ai également créé un formatage qui se produit au chargement de l'application. Cela positionne la sélection dans la cellule supérieure gauche. De plus, je rends mes "boutons" de cadran cliquables et je change leurs couleurs d'arrière-plan et de texte.

//start with selection at upper left
 var worksheet = context.workbook.worksheets.getItem("Sheet1");
 var initSelection = worksheet.getRange("A1");
 initSelection.select();
 
 //format dial buttons
 var range = worksheet.getRange("E:E");
 var conditionalFormat = range.conditionalFormats.add(Excel.ConditionalFormatType.containsText);
 
 conditionalFormat.textComparison.format.font.color = "white";
 conditionalFormat.textComparison.format.fill.color = "purple";
 conditionalFormat.textComparison.rule = {
   operator: Excel.ConditionalTextOperator.contains,
   text: "Dial"
 };

Activation du "bouton" de numérotation

L'une des réalisations les plus satisfaisantes de ce projet est la possibilité de cliquer sur un élément de la feuille Excel et de déclencher un appel téléphonique vers un numéro provenant de cette feuille. Dans mon cas, il s'agit du "bouton" de composition qui apparaît sur chaque ligne de données. J'utilise "bouton" entre guillemets car il ne s'agit pas du tout d'un bouton, mais simplement d'une cellule contenant le mot "Dial". J'ai créé un gestionnaire qui vérifie les changements de sélection et réagit lorsque le texte de la cellule cliquée correspond au mot "Dial".

function handleSelectionChanged(event) {
 return Excel.run(function(context) {
   var range = context.workbook.getSelectedRange().load();
 
   return context.sync().then(function() {
     const selectedContent = JSON.stringify(range.values, null, 4);
 
     const rowString = JSON.stringify(range.rowIndex, null, 4);
 
     const rowIndex = Number(rowString) + 1;
 
     if (selectedContent.match("Dial")) {
       placeCall(rowIndex);
     }
   });
 }).catch(errorHandlerFunction);
}
 
function placeCall(row) {
 return Excel.run(function(context) {
   var toNumberRange = context.workbook.worksheets
     .getItem("Sheet1")
     .getRange("D" + row)
     .load();
 
   return context.sync().then(function() {
     const toNumber = JSON.stringify(toNumberRange.values, null, 4);
 
     VonageDialer.placeCall(toNumber);
   });
 }).catch(errorHandlerFunction);
}

Réagir aux événements de Vonage Communications

Une autre fonction puissante de l'Open ContactPad vous permet de faire en sorte que des choses se produisent dans votre application intégrée en fonction du moment où elle reçoit événements Vonage. Tout ce que vous avez à faire est de regarder le type d'événement (event.type) et de créer un code pour réagir à l'événement. Les détails de ce que mon code fait pour ces événements seront décrits dans la section Sujets avancés. CALL_START, CALL_ANSWER et CALL_END ne sont que quelques-unes des options disponibles. Pour plus d'informations, reportez-vous à la section Modèles de données du SDK.

VonageDialer.init({ /* dialer config options */ }, (dialer) => {
 dialer.setOnDialerEvent((event) => {
   switch (event.type) {
     case 'CALL_START': {
       break;
     }
     case 'CALL_ANSWER': { // available only for UC
       break;
     }
     case 'CALL_END': {
       // do something based on event.data (screen pop, store interaction, etc.)
       break;
     }
     default: {
       console.log('Unhandled event', event);
     }
  }
 });
});

Sujets avancés

Cette section aborde d'autres personnalisations permettant d'adapter l'intégration à vos besoins, comme la mise en œuvre de la recherche de contacts et la définition du contact d'interaction.

Mise en œuvre de la recherche de contacts - Lorsque les lignes Excel deviennent des contacts consultables

Voyons comment rendre les contacts de la feuille de calcul consultables dans le ContactPad.

Fonctionnalité du fournisseur d'ajout de contacts

La première chose à faire pour que les contacts apparaissent est d'activer la fonction contactsProvider dans le cadre de l'initialisation du composeur. Comme le montre la section suivante, il suffit de fixer la valeur à true sous features, et tout sera prêt ! Cette documentation contient plus d'informations sur la création d'un fournisseur d'intégration.

Enregistrer l'icône SVG

Si vous enregistrez une icône, elle sera utilisée pour désigner visuellement l'origine des contacts. Comme il s'agit d'une intégration Excel, j'ai choisi d'utiliser l'icône Excel. J'ai obtenu la base64 à partir de Icon Scout.

VonageDialer.init(
 {
   features: {
     contactsProvider: true,
     openContact: true
   }
 },
 (dialer) => {
   dialer.registerSvgIcon(
     "excel",
     "data: image / svg + xml; utf8; base64, **excel icon SVG data goes here**
   );

Fournir les données de contact - Mettre en œuvre les gestionnaires

Search Contact Data

Aventures dans le formatage des numéros de téléphone

Le formatage, le stockage et la recherche de numéros de téléphone peuvent devenir des tâches assez complexes. Pour en avoir un aperçu, jetez un coup d'œil à cet article de SitePoint qui décrit cette complexité. Heureusement, dans mon propre projet, j'ai le contrôle sur certaines choses. Par exemple, je sais que mon utilisateur n'a qu'un numéro américain. Je règle donc explicitement le code pays de mon composeur sur US.

var countryCode = "US";
VonageDialer.setCountryCode(countryCode);

Je suppose également que tous les numéros de téléphone qui seront saisis sont des numéros américains, j'utilise donc libphonenumber avec le pays américain pour formater les numéros à la fois pour la recherche et l'affichage.

<script src="https://unpkg.com/libphonenumber-js@1.9.6/bundle/libphonenumber-max.js">
</script>

filteredContacts.push(sortedContacts[i]);
const ph = libphonenumber.parsePhoneNumber(sortedContacts[i].phoneNumber, countryCode);

Pour un exemple rapide, mon code est suffisant, mais selon les objectifs de votre mise en œuvre, vous devrez prendre le temps de réfléchir aux nombres de vos utilisateurs, aux nombres qui seront considérés comme des contacts, et mettre en œuvre vos fonctions de recherche avec beaucoup de soin.

Fonctions de traduction et de filtrage des données des contacts

Il s'agit des fonctions que j'ai créées pour convertir les données des contacts du format attendu par le JavaScript d'Excel au format attendu par le JavaScript de Vonage. Elles sont appelées dans le code qui vous permet de rechercher les contacts.

   function translateContacts(excelData) {
     excelData = JSON.parse(excelData);
     let len = excelData.length,
       contactsData = [],
       obj = new Object(),
       objString = "",
       i;
     for (i = 0; i < len; i += 1) {
       if (excelData[i][4] == "Dial") {
         obj["provider"] = "excel";
         obj["id"] = i;
         obj["label"] = excelData[i][2] + " " + excelData[i][1] + " of " + excelData[i][0];
         obj["type"] = "Contact";
         const ph = libphonenumber.parsePhoneNumber(excelData[i][3], countryCode);
         obj["phoneNumber"] = ph.format("INTERNATIONAL").replace(/\D/g, "");
         objString = JSON.stringify(obj);
         contactsData.push(JSON.parse(objString));
       }
     }
     return contactsData;
   }
   function filterContacts(query, contacts) {
     const sortedContacts = contacts.sort(function (a, b) {
       const labelA = a.label.toUpperCase(); // ignore upper and lowercase
       const labelB = b.label.toUpperCase(); // ignore upper and lowercase
       if (labelA < labelB) {
         return -1;
       }
       if (labelA > labelB) {
         return 1;
       }
       // names must be equal
       return 0;
     });
     let filteredContacts = [];
     for (let i = 0; i < sortedContacts.length; i++) {
       if (
         JSON.stringify(Object.values(sortedContacts[i]).filter(item => item !== "excel"))
           .toUpperCase()
           .indexOf(query.toUpperCase()) > 0
       ) {
         filteredContacts.push(sortedContacts[i]);
         const ph = libphonenumber.parsePhoneNumber(sortedContacts[i].phoneNumber, countryCode);
         sortedContacts[i].phoneNumber = ph.format("INTERNATIONAL");
       }
     }
     return filteredContacts;
   }

Création des suggestions de composition

   const searchContactables = (query, callback) => {
     Excel.run(function(context) {
       var worksheet = context.workbook.worksheets.getItem("Sheet1");
 
       var range = worksheet.getRange("A3:E999");
       range.load("values");
 
       return context.sync().then(function() {
         const excelData = JSON.stringify(range.values, null, 4);
         const contactsData = translateContacts(excelData);
 
         const filteredContacts = filterContacts(query.replace(/[^A-Za-z0-9_]/g, ""), contactsData);
 
         callback(filteredContacts);
       });
     }).catch(errorHandlerFunction);
   };
   dialer.setOnSearchContactables(searchContactables);

Définition du contact d'interaction - Affichage des données du contact dans l'interface du composeur

Cette fonctionnalité est décrite dans la section Définir le contenu de l'interaction de la documentation Open ContactPad. Je montre ici comment j'ai mis en œuvre la possibilité d'afficher les coordonnées du numéro distant dans le composeur pendant un appel.

Dialer Interface

 dialer.setOnDialerEvent((event) => {
   //search for contact
   Excel.run(function(context) {
     var worksheet = context.workbook.worksheets.getItem("Sheet1");
     var range = worksheet.getRange("A3:E999");
     range.load("values");
     return context.sync().then(function() {
       const excelData = JSON.stringify(range.values, null, 4);
       const contactsData = translateContacts(excelData);
       const query = "" + event.data.phoneNumber;
       const filteredContacts = filterContacts(query.replace(/[^A-Za-z0-9_]/g, ""), contactsData);
       const interactionContact = filteredContacts[0];
       switch (event.type) {
         case "CALL_START": {
           if (filteredContacts.length > 0) {
             dialer.setInteractionContact(event.data.id, {
               provider: interactionContact.provider,
               id: "" + interactionContact.id,
               label: interactionContact.label,
               type: interactionContact.type
             });
           }
           break;
         }

Mise en œuvre de la possibilité d'"ouvrir" le contact

Open Contact

Ajouter une fonction de contact ouvert

Ce code met en évidence le contact dans la feuille Excel lorsque l'utilisateur clique sur l'icône de lien à partir de la recherche de contact. Pour fonctionner, il faut openContact: true dans les fonctions init fonctionnalités.

case "OPEN_CONTACT": {
     const rowNumber = event.data.id + 3;
     const rowString = "A" + rowNumber + ":D" + rowNumber;
     const row = worksheet.getRange(rowString);
     row.select();
     break;
   }

// Dialer init
VonageDialer.init({
  features: {
    contactsProvider: true,
    openContact: true,
    openActivity: 'acme',
    eventsHistory: true
  }
}, (dialer) => { /* <-- dialer instance */ });

Résumé

J'espère qu'en lisant ceci, vous pourrez créer un composeur Vonage personnalisable qui pourra être utilisé dans de nombreuses Applications différentes. N'hésitez pas à nous faire part de vos commentaires dans la section business-communications-api dans le canal Slack org de la communauté Vonage si vous avez utilisé ces informations pour créer des implémentations utiles.