Sample: Create a mail app for Voice Over IP dialing in Outlook

apps for Office

This sample mail app lets users use a Voice Over IP (VOIP) service to dial telephone numbers in a message or appointment without leaving Outlook.

Last modified: February 17, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0

   Apps for Office manifests schema: v1.0

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this topic, you will learn about the following features:

  • Using the phone number well-known entity to obtain telephone numbers in the subject or body of the currently selected item.

  • Using a shell extension for a VOIP service, such as Lync, to call a telephone number, provided that the VOIP service has registered the callto: and tel: protocols.

A mail app is contextual and is activated when circumstances, with respect to the current item, satisfy the activation rules of the app. In this Phone Dialer example, Outlook activates this app if the subject or body of the selected email message, meeting request, response, or cancellation (in the Reading Pane or inspector), or the selected appointment (in an inspector), contains a telephone number. When the user chooses the app button, the app pane opens and displays each telephone number. The end user can choose one of these telephone numbers to call it using the Lync client.

See the Phone Dialer mail app in Outlook.

Video

Before trying this app the first time, follow the instructions in How to: Install sample mail apps in Outlook to use the Exchange Admin Center to install the app for use in Outlook. Then, create an email message or appointment, and add one or more telephone numbers to the body. When you display the message in the Reading Pane, or the message or appointment in an inspector, Outlook activates the app. You can then choose the Phone Dialer app button, and then choose a telephone number in the app pane to use VOIP to dial that number.

To run this app, you must have access to a VOIP service such as Lync. Using Lync as the VOIP service, this app assumes you have installed the Lync client on the client computer and used it at least once to set it up.

Even though this example uses Lync as the VOIP service, you can adapt the code to use any VOIP service, as long as that service supports and has registered the callto: and tel: protocols.

This section describes the XML manifest, HTML, and JavaScript files for the Phone Dialer mail app.

You can download the source code files for the Phone Dialer mail app at Mail apps for Outlook: Create a mail app for VoIP dialing.

XML manifest

An XML manifest defines the following metadata for an app:

  • Identity.

  • Capability required of the host application

  • Form factors.

  • Corresponding HTML file for possibly each form factor.

  • Display requirements.

  • Necessary permissions.

  • Activation rules.

The manifest uses the OfficeApp element as the root element to enclose various child elements of the MailApp complex type in a sequential order. This section highlights a few areas of interest in the manifest that characterize the Phone Dialer mail app.

  • The type of this app—The OfficeApp element in the following XML line specifies that this app is of the MailApp complex type, which extends the base complex type OfficeApp.

    <OfficeApp 
    xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="MailApp">
    
    
  • The identifier of the app—The Id element in the following XML line uniquely identifies and differentiates this app from other apps for Office.

    <Id>BB10B02E-6F7F-46BB-8DFC-418E8F7986AF</Id>
    
  • The label on the app button—The DisplayName element in the following XML line specifies "Phone Dialer" as the app label. Outlook displays the app button in the app bar if circumstances with respect to the current item satisfy the activation conditions that are specified in the manifest.

    <DisplayName DefaultValue="Phone Dialer"/>
    
  • A verbose description for the app — In the next set of XML lines, the Description element contains a DefaultValue attribute that contains a description of typically the purpose of the app. The DefaultValue attribute corresponds to the en-us locale specified by the DefaultLocale element. You can use an Override child element to support a description for a different locale.

    <Description DefaultValue="Detects phone numbers within a 
    message or appointment and shows the links to call. 
    Only North American phone number formats are currently 
    supported, and you must have some Voice over IP application 
    already installed (like Lync or Skype)."/>
    
    
  • The capabilities that this app requires of a host application—The Capabilities element includes one Capability element in the following XML lines. This means the app requires only one capability, the Mailbox capability. An application that supports the Mailbox capability can become a host application for this app.

    <Capabilities>
      <Capability Name="Mailbox"/>
    </Capabilities>
    
  • The form factor supported by this app, location of the HTML file, and default display height, in pixels—The DesktopSettings element in the following XML lines specifies that this app supports the desktop form factor. The SourceLocation element specifies the URL where Outlook can obtain the dialer.htm file. The RequestedHeight element specifies that Outlook should try to display an app pane that is 150 pixels high.

    Note Note

    If you are trying this Phone Dialer app, you should replace the URL for the HTML file, http://webserver/dialer/dialer.htm, by the actual location of the HTML file in your configuration.

      <DesktopSettings>
        <!-- Change the following line to specify the web server -->
        <!-- where the HTML file is hosted. -->
        <SourceLocation DefaultValue=
          "https://webserver/PhoneDialer/dialer.htm" />
        <RequestedHeight>150</RequestedHeight>
      </DesktopSettings>
    
    
  • The permission requested by this app—The Permissions element in the following XML line specifies that this app requests the read item permission.

    <Permissions>ReadItem</Permissions>
    
  • The activation rules—This app specifies a rule of the ItemHasKnownEntity complex type, and specifies the phone number as an entity to look for in the subject or body of the selected item.

    <Rule xsi:type="ItemHasKnownEntity" 
        EntityType="PhoneNumber"/>
    
  • Setting to enable or disable highlighting instances of entities specified in the manifest—The DisableEntityHighlighting element in the following XML line specifies a value of false to disable highlighting entities in the item body that match the regular expression.

    <DisableEntityHighlighting>false</DisableEntityHighlighting>
    

See Appendix A: XML manifest for a complete listing of the XML manifest.

HTML implementation

The HTML code defines the user interface for this app. This section highlights a few areas of interest in the HTML file for this app.

  • A document mode for Internet Explorer 9—Because Outlook uses Internet Explorer 9 components in a browser control to open the HTML page, you must place the following HTML line as a child element of the head element in your HTML file, before all other elements except for the title element and other meta elements.

    <meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
    
  • Location of the JavaScript libraries and app-specific JavaScript file—As described in the previous section, the XML manifest specifies the location of the HTML file, and the HTML file, in turn, specifies the JavaScript libraries and JavaScript file for this app. The HTML file specifies that the JavaScript API library file, Office.js, is to be accessed from the Content Delivery Network (CDN), and that the other JavaScript library files, jquery-1.4.2.js, MicrosoftAjax.js, as well as dialer.js, are in the subfolder Scripts, in relation to the HTML file, as shown in the following HTML lines.

        <script type="text/javascript" 
            src="Scripts/jquery-1.4.2.js"></script>
        <script type="text/javascript" 
            src="Scripts/MicrosoftAjax.js"></script>
        <!-- Use the CDN reference to Office.js when deploying your app. -->
        <script type="text/javascript" 
            src="https://appsforoffice.microsoft.com/lib/1.0/hosted/Office.js"></script>
        <script type="text/javascript" 
            src="Scripts/dialer.js"></script>
    
    
  • Use of the Outlook.css style sheet—The following HTML line specifies the optional use of the Outlook.css style sheet.

        <link rel="stylesheet" type="text/css" 
            href="Css/Outlook.css" />
    
  • The event handler for the onload event—When the browser loads the HTML body, the onload event occurs. The following line specifies the loadcomplete method as the event handler, which is defined in the JavaScript file.

    <body onload="loadcomplete()">
    
  • The main section of the HTML file specifies the appearance of the webpage, defines a section named dialerholder that the JavaScript code can dynamically update and display the telephone numbers from the item body.

        <div>
            <table>
                <tr>
                    <td rowspan="2">
                        <img src="Images/Icon_narrow.png" 
                            alt='Phone Dialer' align="top" />
                    </td>
                    <td style="font-family: Segoe UI; Font-size: 10pt;"
                        valign="top">
                        <b>Click to Call:</b>
                    </td>
                </tr>
                <tr>
                    <td style="font-family: Segoe UI; font-size: 10pt;"
                        valign="middle" align="center">
                        <div id="dialerholder">
                        </div>
                    </td>
                </tr>
            </table>
        </div>
        <div>
    
    
  • The bottom of the user interface provides support for end users who have questions or feedback.

            <p style="font-family: Segoe UI; font-size: 10pt;" 
               class="supportLabel">
                <i>Please <a id="support" href=
                "mailto:Support@contoso.com?subject=Phone Dialer Feedback&body=">
                contact</a> for any feedback.</i>
            </p>
    
    

See Appendix B: HTML file for a complete listing of the HTML file.

JavaScript implementation

The JavaScript code supports the app functionality behind the user interface in the app pane. This section highlights a few areas of interest in the JavaScript file for this app:

  • Defining the loadcomplete function—An app defines this event handler for the onload event to signify that the browser has loaded the HTML body and the DOM is ready. This function sets bodyload to true. This app checks the two flags—bodyload and init (which is set by the onInitializeComplete function to signify that the run-time environment is loaded)—before calling the main function of the app, initDialer.

    function loadcomplete() {
        bodyload = true;
        if (bodyload && init) 
            initDialer();
    }
    
    
  • Defining the initialize function—Every app for Office must define an event handler for the initialize event, which occurs when the run-time environment is loaded. This initialize event handler gets the Mailbox object from the Office.context.mailbox property. Then it gets the current item from the item property of the Mailbox object. The event handler then calls the onInitializeComplete function.

    // The initialize function is required for all apps.
    Office.initialize = function () {
        item = Office.context.mailbox.item;
        onInitializeComplete();
    }
    
    
  • Defining the onInitializeComplete function—This function is called by the initialize event handler when the run-time environment is loaded. This function sets init to true. The app checks the two flags—bodyload (which is set by the loadcomplete function to signify that the browser has loaded the HTML page and the DOM is ready) and init—before calling the main function of the app, initDialer.

    // Handler for initialization complete.
    function onInitializeComplete() {
        init = true;
        if (bodyload && init) {
            initDialer();
        }
    }
    
    
  • Calling the app main function initDialer—As seen in the loadcomplete and onInitializeComplete functions, this app ensures that both the initialize event and the HTML page onload event have occurred, and that the app is ready to interact with Outlook, before calling the main function, initDialer.

  • Displaying telephone numbers in the item body as links—The main function of this app, initDialer, uses the getEntities method of the current item to return an array of supported entities in the subject or body of the current item. initDialer then uses the phoneNumbers property to get an array of one or more phone numbers among the entities. Because selected item satisfies the ItemHasKnownEntity rule in the manifest and the host application activated this app, the selected item must contain at least one telephone number. initDialer parses the array, associates each telephone number with a callto:tel: hyperlink. When the user chooses one of these links, Lync opens and the user can proceed to use Lync to dial the number.

    For more information about the shell extensions that Lync Server supports, see Executing the Communicator 2007 Shell.

    // Initialze dialer.
    function initDialer() {
        var numbers = item.getEntities().phoneNumbers;
        var htmlElement = document.getElementById('dialerholder');
        var supportElement = document.getElementById('support');
        var htmlToShow = "";
    
        if (numbers == null || numbers.length == 0) {
            htmlElement.innerHTML = 
            "<b style='color:Red'>Error happened while getting 
            phone numbers. Please contact to report this issue.<b>";
            supportElement.href += "Phone Numbers Entity is Null";
            return;
        }
    
        $.each(numbers, function (i, number) {
            htmlToShow += "<br><a href='callto:tel:" + 
            number.phoneString + "'>" + 
            number.originalPhoneString + "</a>";
        });
    
        htmlElement.innerHTML = htmlToShow;
        supportElement.href += "Phone Numbers Length is: " + 
            numbers.length;
    }
    
    

See Appendix C: JavaScript file for a complete listing of the JavaScript file.

In general, you can apply the code in this app to work with any VOIP service that has registered the callto: and tel: protocols. This topic uses Lync 2013 as an example, and assumes that the end user has installed the Lync client and used it at least once to set it up on the client computer.

Try adapting this code for other VOIP services that support the same protocols.

The following is a listing of the XML manifest for the Phone Dialer mail app.

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp 
xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="MailApp">
  <Id>BB10B02E-6F7F-46BB-8DFC-418E8F7986AF</Id>
  <Version>1.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Phone Dialer"/>
  <Description DefaultValue="Detects phone numbers within a 
message or appointment and shows the links to call. 
Only North American phone number formats are currently 
supported, and you must have some Voice over IP application 
already installed (like Lync or Skype)."/>
  <!-- Change the following line to specify the web server -->
  <!-- where the icon file is hosted. -->
  <IconUrl DefaultValue=
    "https://webserver/PhoneDialer/Images/Icon.png" />
  <Capabilities>
    <Capability Name="Mailbox"/>
  </Capabilities> 
  <DesktopSettings>
    <!-- Change the following line to specify the web server -->
    <!-- where the HTML file is hosted. -->
    <SourceLocation DefaultValue=
      "https://webserver/PhoneDialer/dialer.htm" />
    <RequestedHeight>150</RequestedHeight>
  </DesktopSettings>
  <Permissions>ReadItem</Permissions>
  <Rule xsi:type="ItemHasKnownEntity" 
    EntityType="PhoneNumber"/>
  <DisableEntityHighlighting>false</DisableEntityHighlighting>
</OfficeApp>

The following is a listing of the HTML file for the Phone Dialer mail app.

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
    <style type="text/css">
        .supportLabel
        {
            bottom: 5px;
            left: 5px;
            z-index: 10;
            font-size: 10px;
            white-space: nowrap;
        }
    </style>
    <title>Phone Dialer</title>
    <link rel="stylesheet" type="text/css" href="Css/Outlook.css" />
    <script type="text/javascript" src="Scripts/jquery-1.4.2.js"></script>
    <script type="text/javascript" src="Scripts/MicrosoftAjax.js"></script>
    <!-- Use the CDN reference to Office.js when deploying your app. -->
    <script type="text/javascript" 
        src="https://appsforoffice.microsoft.com/lib/1.0/hosted/Office.js"></script>
    <script type="text/javascript" src="Scripts/dialer.js"></script>
</head>
<body onload="loadcomplete()">
    <div>
        <table>
            <tr>
                <td rowspan="2">
                    <img src="Images/Icon_narrow.png" alt='Phone Dialer' align="top" />
                </td>
                <td style="font-family: Segoe UI; font-size: 10pt;" valign="top">
                    <b>Click to Call:</b>
                </td>
            </tr>
            <tr>
                <td style="font-family: Segoe UI; font-size: 10pt;" valign="middle" 
align="center">
                    <div id="dialerholder">
                    </div>
                </td>
            </tr>
        </table>
    </div>
    <div>
        <p style="font-family: Segoe UI; font-size: 10pt;" class="supportLabel">
            <i>Please <a id="support" href="mailto:ExDogAgave@microsoft.com?subject=Phone Dialer 
Feedback&body=">
                Contact</a> for any feedback.</i>
        </p>
    </div>
</body>
</html>

The following is a listing of the JavaScript file for the Phone Dialer mail app.

var init = false;
var bodyload = false
var item;

// The initialize function is required for all apps.
Office.initialize = function () {
    item = Office.context.mailbox.item;
    onInitializeComplete();
}

// Initialze dialer.
function initDialer() {
    var numbers = item.getEntities().phoneNumbers;
    var htmlElement = document.getElementById('dialerholder');
    var supportElement = document.getElementById('support');
    var htmlToShow = "";

    if (numbers == null || numbers.length == 0) {
        htmlElement.innerHTML = 
        "<b style='color:Red'>Error happened while getting 
        phone numbers. Please contact to report this issue.<b>";
        supportElement.href += "Phone Numbers Entity is Null";
        return;
    }

    $.each(numbers, function (i, number) {
        htmlToShow += "<br><a href='callto:tel:" + 
        number.phoneString + "'>" + 
        number.originalPhoneString + "</a>";
    });

    htmlElement.innerHTML = htmlToShow;
    supportElement.href += "Phone Numbers Length is: " + 
        numbers.length;
}

// Handler for initialization complete.
function onInitializeComplete() {
    init = true;
    if (bodyload && init) {
        initDialer();
    }
}

// Handler for app body onload.
function loadcomplete() {
    bodyload = true;
    if (bodyload && init) {
        initDialer();
    }
}

Show:
© 2014 Microsoft