Edit

Create an Outlook add-in for an online-meeting provider

  • Article

Setting up an online meeting is a core experience for an Outlook user, and it's easy to create a Teams meeting with Outlook. However, creating an online meeting in Outlook with a non-Microsoft service can be cumbersome. By implementing this feature, service providers can streamline the online meeting creation and joining experience for their Outlook add-in users.

Important

This feature is supported in Outlook on the web, Windows (classic and new (preview)), Mac, Android, and iOS with a Microsoft 365 subscription.

In this article, you'll learn how to set up your Outlook add-in to enable users to organize and join a meeting using your online-meeting service. Throughout this article, we'll use a fictional online-meeting service provider, "Contoso".

Set up your environment

Complete the Outlook quick start which creates an add-in project with the Yeoman generator for Office Add-ins.

Configure the manifest

To enable users to create online meetings with your add-in, you must configure the manifest. The markup differs depending on two variables:

If your add-in uses an XML manifest, and the add-in will only be supported in Outlook on the web, Windows (classic and new (preview)), and Mac, select the Windows, Mac, web tab for guidance. However, if your add-in will also be supported in Outlook on Android and iOS, select the Mobile tab.

If the add-in uses the unified manifest (preview), select the Unified manifest for Microsoft 365 (developer preview) tab.

Important

Online meeting providers aren't yet supported for the unified manifest (preview). We're working on providing that support soon.

  1. In your code editor, open the Outlook quick start project you created.

  2. Open the manifest.xml file located at the root of your project.

  3. Select the entire <VersionOverrides> node (including open and close tags) and replace it with the following XML.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Description resid="residDescription"></Description>
    <Requirements>
      <bt:Sets>
        <bt:Set Name="Mailbox" MinVersion="1.3"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <FunctionFile resid="residFunctionFile"/>
          <ExtensionPoint xsi:type="AppointmentOrganizerCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="apptComposeGroup">
                <Label resid="residDescription"/>
                <Control xsi:type="Button" id="insertMeetingButton">
                  <Label resid="residLabel"/>
                  <Supertip>
                    <Title resid="residLabel"/>
                    <Description resid="residTooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="icon-16"/>
                    <bt:Image size="32" resid="icon-32"/>
                    <bt:Image size="64" resid="icon-64"/>
                    <bt:Image size="80" resid="icon-80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>insertContosoMeeting</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="icon-16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
        <bt:Image id="icon-32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
        <bt:Image id="icon-48" DefaultValue="https://contoso.com/assets/icon-48.png"/>
        <bt:Image id="icon-64" DefaultValue="https://contoso.com/assets/icon-64.png"/>
        <bt:Image id="icon-80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="residFunctionFile" DefaultValue="https://contoso.com/commands.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="residDescription" DefaultValue="Contoso meeting"/>
        <bt:String id="residLabel" DefaultValue="Add a contoso meeting"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="residTooltip" DefaultValue="Add a contoso meeting to this appointment."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Tip

To learn more about manifests for Outlook add-ins, see Office add-in manifests and Add support for add-in commands in Outlook on mobile devices.

Implement adding online meeting details

In this section, learn how your add-in script can update a user's meeting to include online meeting details. The following applies to all supported platforms.

  1. From the same quick start project, open the file ./src/commands/commands.js in your code editor.

  2. Replace the entire content of the commands.js file with the following JavaScript.

    // 1. How to construct online meeting details.
// Not shown: How to get the meeting organizer's ID and other details from your service.
const newBody = '<br>' +
    '<a href="https://contoso.com/meeting?id=123456789" target="_blank">Join Contoso meeting</a>' +
    '<br><br>' +
    'Phone Dial-in: +1(123)456-7890' +
    '<br><br>' +
    'Meeting ID: 123 456 789' +
    '<br><br>' +
    'Want to test your video connection?' +
    '<br><br>' +
    '<a href="https://contoso.com/testmeeting" target="_blank">Join test meeting</a>' +
    '<br><br>';

let mailboxItem;

// Office is ready.
Office.onReady(function () {
        mailboxItem = Office.context.mailbox.item;
    }
);

// 2. How to define and register a function command named `insertContosoMeeting` (referenced in the manifest)
//    to update the meeting body with the online meeting details.
function insertContosoMeeting(event) {
    // Get HTML body from the client.
    mailboxItem.body.getAsync("html",
        { asyncContext: event },
        function (getBodyResult) {
            if (getBodyResult.status === Office.AsyncResultStatus.Succeeded) {
                updateBody(getBodyResult.asyncContext, getBodyResult.value);
            } else {
                console.error("Failed to get HTML body.");
                getBodyResult.asyncContext.completed({ allowEvent: false });
            }
        }
    );
}
// Register the function.
Office.actions.associate("insertContosoMeeting", insertContosoMeeting);

// 3. How to implement a supporting function `updateBody`
//    that appends the online meeting details to the current body of the meeting.
function updateBody(event, existingBody) {
    // Append new body to the existing body.
    mailboxItem.body.setAsync(existingBody + newBody,
        { asyncContext: event, coercionType: "html" },
        function (setBodyResult) {
            if (setBodyResult.status === Office.AsyncResultStatus.Succeeded) {
                setBodyResult.asyncContext.completed({ allowEvent: true });
            } else {
                console.error("Failed to set HTML body.");
                setBodyResult.asyncContext.completed({ allowEvent: false });
            }
        }
    );
}

Testing and validation

Follow the usual guidance to test and validate your add-in, then sideload the manifest in Outlook on the web, on Windows (classic or new (preview)), or on Mac. If your add-in also supports mobile, restart Outlook on your Android or iOS device after sideloading. Once the add-in is sideloaded, create a new meeting and verify that the Microsoft Teams or Skype toggle is replaced with your own.

Create meeting UI

As a meeting organizer, you should see screens similar to the following three images when you create a meeting.

The create meeting screen on Android with the Contoso toggle off. The create meeting screen on Android with a loading Contoso toggle. The create meeting screen on Android with the Contoso toggle on.

Join meeting UI

As a meeting attendee, you should see a screen similar to the following image when you view the meeting.

The join meeting screen on Android.

Important

The Join button is only supported in Outlook on the web, on Mac, on Android, on iOS, and in new Outlook on Windows (preview). If you only see a meeting link, but don't see the Join button in a supported client, it may be that the online-meeting template for your service isn't registered on our servers. See the Register your online-meeting template section for details.

Register your online-meeting template

Registering your online-meeting add-in is optional. It only applies if you want to surface the Join button in meetings, in addition to the meeting link. Once you've developed your online-meeting add-in and would like to register it, create a GitHub issue using the following guidance. We'll contact you to coordinate a registration timeline.

Important

The Join button is only supported in Outlook on the web, on Mac, on Android, on iOS, and in new Outlook on Windows (preview).

  1. Create a new GitHub issue.
  2. Set the Title of the new issue to "Outlook: Register the online-meeting template for my-service", replacing my-service with your service name.
  3. In the issue body, replace the existing text with the string you set in the newBody or similar variable from the Implement adding online meeting details section earlier in this article.
  4. Click Submit new issue.

A new GitHub issue screen with Contoso sample content.

Available APIs

The following APIs are available for this feature.

Restrictions

Several restrictions apply.

  • Applicable only to online-meeting service providers.
  • Only admin-installed add-ins will appear on the meeting compose screen, replacing the default Teams or Skype option. User-installed add-ins won't activate.
  • The add-in icon should be in grayscale using hex code #919191 or its equivalent in other color formats.
  • Only one function command is supported in Appointment Organizer (compose) mode.
  • The add-in should update the meeting details in the appointment form within the one-minute timeout period. However, any time spent in a dialog box the add-in opened for authentication, for example, is excluded from the timeout period.

See also