Telefonanrufe mit Microsoft Excel und Vonage Open ContactPad SDK tätigen

Einführung

Auf dieser Seite erkläre ich, wie ich in kurzer Zeit eine funktionierende VBC-Integration mit einer Drittanbieter-Plattform unter Verwendung des neuen Vonage Open ContactPad aufgebaut habe. Zunächst finden Sie hier ein Video, das die verfügbaren Funktionen der Integration zeigt.

Ausgewählte Anwendung - Microsoft Excel Online

Ich habe ausgewählt Microsoft Excel Online ausgewählt, weil ich kürzlich gelesen hatte, dass Microsoft eine JavaScript-API für Excel veröffentlicht hat. Viele Leute verwenden das Programm für die Arbeit mit Tabellenkalkulationen, und ich fand, dass es eine recht unkomplizierte Möglichkeit ist, mit den Daten umzugehen. Microsoft Excel ermöglicht Integrationen durch Office-Add-Ins. Ein sehr cooles Add-In ist Skript-Labormit dem Entwickler mit der Erstellung von Add-Ins experimentieren können. In dieser Anleitung wird der Code in Script Lab mit Hilfe von Excel- und Vonage-JavaScript-Funktionen hinzugefügt und das Ergebnis dann in einem GitHub Gist. Um von dort aus weiterzukommen, kann der Leser interessiert sein an Veröffentlichung von Office Add-Ins.

Mitmachen in Microsoft Excel Online

Um das Beste aus dieser Anleitung herauszuholen, wird empfohlen, das Script Lab Office Add-In zu installieren und die Gist von Github zu importieren:

Die Gist enthält den vollständigen Quellcode, den Sie für Ihr Projekt anpassen können. Die Beispiele unten sind teilweise sehr spezifisch und enthalten nicht alles, was Sie brauchen, um eine bestimmte Funktion zum Laufen zu bringen.

Erste Schritte mit dem Vonage Open ContactPad

Die Vonage Open ContactPad SDK ist ein JavaScript-Softwareentwicklungs-Toolkit, das es Entwicklern ermöglicht, eine Vonage Unified Communications (UC) Dialer-Schnittstelle in eine webbasierte Anwendung einbetten können. Es erfordert zwar eine Anmeldung mit einer Vonage Business Communications Account erfordert, können Sie mit dem SDK ohne zusätzliche API-Benutzer oder Anmeldungen entwickeln. Damit steht Entwicklern, die Kommunikationsclients in ihre Applikationen einbinden möchten, ein sehr einfaches Integrationsframework zur Verfügung.

Warum Microsoft Excel Online und nicht die PC/Mac-Anwendung?

Es ist wichtig zu beachten, dass das Vonage Open ContactPad SDK-Produkt für die Einbettung in Webanwendungen gedacht ist und am besten funktioniert, wenn der Entwickler die volle Kontrolle über den Bereich hat, in dem es eingebettet ist. Es gibt einen Hinweis am Ende der Seite "Erste Schritte der genau diesen Punkt hervorhebt.

Einrichten des Skriptlabors und erste Codezeilen

Wenn Sie Script Lab in Excel installieren, wird ein Script Lab-Menüpunkt rechts neben dem Menüpunkt Hilfe erstellt. Klicken Sie auf die Registerkarte, dann sehen Sie 3 Schaltflächen, die Ihnen die Arbeit mit Script Lab erleichtern - Code, Ausführen und Funktionen. Klicken Sie dann auf Code. Es erscheint ein in die Excel-Oberfläche eingebettetes Fenster mit einem VisualStudio-ähnlichen Fenster, das Ihren Code enthält. Solange Sie den Cache Ihres Browsers nicht leeren, bleibt Ihr Script Lab-Code erhalten. Wenn Sie mehr Dauerhaftigkeit bevorzugen, verwenden Sie die Option Teilen, um Ihren Code als gist auf GitHub. Bei meinen Abenteuern habe ich eine Menge privater Gists erstellt. Wenn ich an einem echten Integrationsprojekt arbeiten würde, würde ich meinen Code wahrscheinlich nach Visual Studio Code übertragen und mit einer genaueren Versionskontrolle arbeiten.

Nachdem ich mich in Script Lab zurechtgefunden hatte, begann ich mit dem HTML-Abschnitt, in den ich meinen Dialer einbetten wollte. Schauen Sie sich die Anweisungen hier an, um Laden des Open ContactPad. Diese enthält ein Live-Beispiel wie man dies mit Hilfe von Plunker.

In meinem Fall wollte ich einen <div> Container bereitstellen, damit meine Anwendung in der vollständigen Dialer-Schnittstelle erscheint und nicht als beweglicher Punkt auf der Seite. Ich setzte den Data-Provider als uc festgelegt, um den Unified Communications-Dialer zu laden.

<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>

Das Erstaunliche daran ist, dass Sie HIER STOPPEN können, den Code ausführen und einen eingebetteten Dialer in Microsoft Excel Online haben! Es gibt jedoch noch viel mehr, was Entwickler tun können, um das Erlebnis zu individualisieren.

Erkunden der Excel-API - Einrichten der Beispieldaten

Warum also Beispieldaten einrichten? Nun, ich wollte den Benutzern Beispiele dafür geben, wie ich das Format und die Position der Daten in der Kalkulationstabelle haben möchte, damit der Code weiß, wo er sie finden muss. Ich wollte einen anklickbaren Bereich, um einen Telefonanruf für jeden "Kontakt" (Zeile) auszulösen und einen Platz für eine Telefonnummer festzulegen. Ich begann mit dem HTML-Code für die Anwendung in Script Lab und fügte eine Schaltfläche hinzu, die die Daten in den gewünschten Abschnitt des Arbeitsblatts einfügen würde. Wenn Sie diese Schaltfläche mehrmals drücken, werden die Daten auf dem Blatt einfach überschrieben.

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

Der nächste Schritt ist die Implementierung der Funktion populateSampleData() in JavaScript. Glücklicherweise ist die Microsoft Excel JavaScript-API-Dokumentation einige Beispiele.

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);
}

Zunächst wählen Sie das erste Arbeitsblatt aus, das in einer leeren Excel-Datei normalerweise als "Blatt1" bezeichnet wird. Dann erstellen Sie ein Objekt mit den Daten, die in das Blatt eingegeben werden. Legen Sie dann den Bereich so fest, dass er die Anzahl der Zellen abdeckt, die die Daten einnehmen werden, und setzen Sie die Werte des Bereichs auf das Datenobjekt. Durch die automatische Anpassung der Spalten wird die Darstellung etwas übersichtlicher.

Ich habe auch eine Formatierung erstellt, die beim Laden der Anwendung erfolgt. Dadurch wird die Auswahl in der oberen linken Zelle positioniert. Außerdem kann ich die Schaltflächen meiner Wahl anklicken und ihre Hintergrund- und Textfarben ändern.

//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"
 };

Aktivieren der Wählscheibe "Button"

Eine der befriedigendsten Errungenschaften dieses Projekts ist die Möglichkeit, auf etwas in der Excel-Tabelle zu klicken und einen Telefonanruf an eine Nummer auszulösen, die aus dieser Tabelle stammt. In meinem Fall ist das die Schaltfläche "Wählen", die in jeder Datenzeile erscheint. Ich verwende "Schaltfläche" in Anführungszeichen, weil es gar keine Schaltfläche ist, sondern nur eine Zelle mit dem Wort "Wählen". Ich habe einen Handler erstellt, der auf Auswahländerungen prüft und reagiert, wenn der Text der angeklickten Zelle mit dem Wort "Dial" übereinstimmt.

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);
}

Reaktion auf Ereignisse bei Vonage Communications

Eine weitere leistungsstarke Funktion des Open ContactPad ermöglicht es Ihnen, bestimmte Vorgänge in Ihrer integrierten Anwendung auszulösen, wenn diese Ereignisse empfangen werden Vonage-Ereignisse. Alles, was Sie tun müssen, ist, sich den Ereignistyp (event.type) anzusehen und Code zu erstellen, der auf das Ereignis reagiert. Die Details meines Codes für diese Ereignisse werden im Bereich Fortgeschrittene Themen beschrieben. CALL_START, CALL_ANSWER und CALL_END sind nur einige der verfügbaren Optionen. Weitere Informationen finden Sie in den SDK-Datenmodelle.

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);
     }
  }
 });
});

Fortgeschrittene Themen

In diesem Abschnitt werden weitere Anpassungen behandelt, mit denen Sie die Integration nach Ihren Wünschen gestalten können, wie z. B. die Implementierung der Kontaktsuche und die Einstellung des Interaktionskontakts.

Implementierung der Kontaktsuche - Wo Excel-Zeilen zu durchsuchbaren Kontakten werden

Schauen wir uns an, wie man die Kontakte in der Tabelle in ContactPad durchsuchbar macht.

Anbieterfunktion Kontakte hinzufügen

Damit die Kontakte angezeigt werden, müssen Sie zunächst die Funktion contactsProvider im Rahmen der Dialer-Initialisierung aktivieren. Wie im nächsten Abschnitt gezeigt, setzen Sie einfach den Wert unter features auf true, und schon sind Sie fertig! Diese Dokumentation enthält weitere Informationen über die Erstellung eines Integrationsanbieters.

SVG-Symbol registrieren

Wenn Sie ein Symbol registrieren, wird es verwendet, um visuell zu kennzeichnen, woher die Kontakte kommen. Da es sich um eine Excel-Integration handelt, habe ich das Excel-Symbol verwendet. Ich habe das base64 von 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**
   );

Bereitstellen der Kontaktdaten - Implementieren der Handler

Search Contact Data

Abenteuer bei der Formatierung von Telefonnummern

Das Formatieren, Speichern und Durchsuchen von Telefonnummern kann sehr aufwändig werden. Um einen Vorgeschmack zu bekommen, werfen Sie einen Blick auf diesen SitePoint-Artikel in dem die Komplexität beschrieben wird. Glücklicherweise habe ich bei meinem eigenen Projekt einige Dinge unter Kontrolle. Zum einen weiß ich, dass mein Benutzer nur eine US-Nummer hat. Also habe ich die Landesvorwahl meines Dialers explizit auf US gesetzt.

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

Ich gehe auch davon aus, dass alle Telefonnummern, die eingegeben werden, US-Nummern sind, also verwende ich libphonenumber mit dem US-Land, um die Numbers sowohl für die Suche als auch für die Anzeige zu formatieren.

<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);

Für ein schnelles Beispiel ist mein Code ausreichend, aber je nach Ihren Zielen mit Ihrer Implementierung, werden Sie Zeit damit verbringen wollen, die Numbers Ihrer Benutzer zu berücksichtigen, die Nummern, die als Kontakte betrachtet werden, und Ihre Suchfunktionen sehr sorgfältig zu implementieren.

Funktionen zum Übersetzen und Filtern der Kontaktdaten

Dies sind die Funktionen, die ich erstellt habe, um die Kontaktdaten aus dem Format, das Excel's JavaScript erwartet, in das Format zu übersetzen, das Vonage's JavaScript erwartet. Sie werden in dem Code aufgerufen, mit dem Sie die Kontakte durchsuchen können.

   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;
   }

Erstellen von Wahlvorschlägen

   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);

Einstellen des Interaktionskontakts - Anzeigen von Kontaktdaten in der Dialer-Schnittstelle

Diese Funktionalität wird im Abschnitt Interaktionsinhalt festlegen Abschnitt der Open ContactPad Dokumentation beschrieben. Hier zeige ich, wie ich die Möglichkeit implementiert habe, dass die Kontaktinformationen der entfernten Nummer während eines Anrufs im Dialer erscheinen.

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;
         }

Implementierung der Möglichkeit, den Kontakt zu "öffnen"

Open Contact

Funktion "Offener Kontakt" hinzufügen

Dieser Code hebt den Kontakt in der Excel-Tabelle hervor, wenn der Benutzer auf das Link-Symbol in der Kontaktsuche klickt. Um zu funktionieren, benötigt er openContact: true in den Dialer init Funktionen.

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 */ });

Zusammenfassung

Ich hoffe, dass Sie nach der Lektüre dieses Artikels einen anpassbaren Vonage Dialer erstellen können, der in vielen verschiedenen Applikationen eingesetzt werden kann. Bitte teilen Sie dies im business-kommunikation-api Kanal in der Vonage Community Slack org, wenn Sie diese Informationen genutzt haben, um nützliche Implementierungen zu erstellen.