Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
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".
Important
This feature is supported in Outlook on the web, Windows (new and classic), Mac, Android, and iOS with a Microsoft 365 subscription.
Set up your environment
Complete the Outlook quick start in which you create an add-in project with the Yeoman generator for Office Add-ins.
Configure the manifest
The steps for configuring the manifest depend on which type of manifest you selected in the quick start.
Note
Add-ins that use the unified manifest for Microsoft 365 aren't supported in Outlook on Mac and on mobile devices. We're working hard to provide support in Mac and mobile devices. In the meantime, to support these platforms, you need to create a version of your add-in that uses the add-in only manifest and then deploy and maintain both versions. For more information, see the "Client and platform support" section of Office Add-ins with the unified app manifest for Microsoft 365.
Open the manifest.json file.
Find the first object in the
"authorization.permissions.resourceSpecific"array and set its"name"property to"MailboxItem.ReadWrite.User". It should look like this when you're done.{ "name": "MailboxItem.ReadWrite.User", "type": "Delegated" }Add the following object to the
"extensions.runtimes"array. Note the following about this code.- The
"minVersion"of the Mailbox requirement set is set to"1.3"so the runtime won't launch on platforms and Office versions where this feature isn't supported. - The
"id"of the runtime is set to the descriptive name"online_meeting_runtime". - The
"code.page"property is set to the URL of UI-less HTML file that will load the function command. - The
"lifetime"property is set to"short"which means that the runtime starts up when the function command button is selected and shuts down when the function completes. (In certain rare cases, the runtime shuts down before the handler completes. See Runtimes in Office Add-ins.) - There's an action to run a function named
"insertContosoMeeting". You'll create this function in a later step.
{ "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ], "formFactors": [ "desktop" ] }, "id": "online_meeting_runtime", "type": "general", "code": { "page": "https://localhost:3000/commands.html" }, "lifetime": "short", "actions": [ { "id": "insertContosoMeeting", "type": "executeFunction" } ] }- The
Replace the
"extensions.ribbons"array with the following. Note the following about this markup.- The
"minVersion"of the Mailbox requirement set is set to"1.3"so the the ribbon customizations won't appear on platforms and Office versions where this feature is not supported. - The
"contexts"array specifies that the ribbon is available only in the meeting details organizer window. - There will be a custom control group on the default ribbon tab (of the meeting details organizer window) labelled Contoso meeting.
- The group will have a button labelled Add meeting.
- The button's
"actionId"has been set to"insertContosoMeeting", which matches the"id"of the action you created in the previous step.
"ribbons": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ], "scopes": [ "mail" ], "formFactors": [ "desktop" ] }, "contexts": [ "meetingDetailsOrganizer" ], "tabs": [ { "builtInTabId": "TabDefault", "groups": [ { "id": "apptComposeGroup", "label": "Contoso meeting", "controls": [ { "id": "insertMeetingButton", "type": "button", "label": "Add meeting", "icons": [ { "size": 16, "url": "icon-16.png" }, { "size": 32, "url": "icon-32.png" }, { "size": 64, "url": "icon-64_02.png" }, { "size": 80, "url": "icon-80.png" } ], "supertip": { "title": "Add a Contoso meeting", "description": "Add a Contoso meeting to this appointment." }, "actionId": "insertContosoMeeting", } ] } ] } ] } ]- The
Add mobile support
Open the manifest.json file.
In the
"extensions.ribbons.requirements.formFactors"array, add"mobile"as an item. When you're finished, the array should look like the following.
"formFactors": [
"desktop",
"mobile"
]
- In the
"extensions.ribbons.contexts"array, addonlineMeetingDetailsOrganizeras an item. When you're finished, the array should look like the following.
"contexts": [
"meetingDetailsOrganizer",
"onlineMeetingDetailsOrganizer"
],
- In the
"extensions.ribbons.tabs"array, find the tab with the"builtInTabId"of"TabDefault". Add a child"customMobileRibbonGroups"array to it (as a peer of the existing"groups"property). When you're finished, the"tabs"array should look like the following:
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
<-- non-mobile group objects omitted -->
],
"customMobileRibbonGroups": [
{
"id": "mobileApptComposeGroup",
"label": "Contoso Meeting",
"controls": [
{
"id": "mobileInsertMeetingButton",
"label": "Add meeting",
"type": "mobileButton",
"actionId": "insertContosoMeeting",
"icons": [
{
"scale": 1,
"size": 25,
"url": "https://localhost:3000/assets/icon-25.png"
},
{
"scale": 1,
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"scale": 1,
"size": 48,
"url": "https://localhost:3000/assets/icon-48.png"
},
{
"scale": 2,
"size": 25,
"url": "https://localhost:3000/assets/icon-25.png"
},
{
"scale": 2,
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"scale": 2,
"size": 48,
"url": "https://localhost:3000/assets/icon-48.png"
},
{
"scale": 3,
"size": 25,
"url": "https://localhost:3000/assets/icon-25.png"
},
{
"scale": 3,
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"scale": 3,
"size": 48,
"url": "https://localhost:3000/assets/icon-48.png"
}
]
}
]
}
]
}
]
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.
From the same quick start project, open the file ./src/commands/commands.js in your code editor.
Replace the entire content of the commands.js file with the following JavaScript.
// 1. Construct online meeting details. // Not shown: How to get the meeting organizer's ID and other details from your service. const newBody = '
' + 'Join Contoso meeting' + '
' + 'Phone Dial-in: +1(123)456-7890' + '
' + 'Meeting ID: 123 456 789' + '
' + 'Want to test your video connection?' + '
' + 'Join test meeting' + '
'; let mailboxItem; Office.onReady(function () { mailboxItem = Office.context.mailbox.item; } ); // 2. 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. 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 }); } } ); }
Test and validate your add-in
To test and validate your add-in, sideload the manifest in Outlook on the web or on Windows (new or classic). If you're using the add-in only manifest, you can also sideload on Mac. For an add-in that 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.
Note
Add-ins that use the unified manifest can't be sideloaded in Outlook on Mac or on mobile devices. To run this type of add-in, the add-in must first be published to Microsoft Marketplace then deployed in the Microsoft 365 Admin Center. For more information, see the "Client and platform support" section of Office Add-ins with the unified app manifest for Microsoft 365.
Create meeting UI
The meeting organizer's UI varies depending on the Outlook client.
Outlook on the web and the new Outlook on Windows
Classic Outlook on Windows
Outlook on Mac
Outlook on mobile devices
Join meeting UI
The meeting attendee's UI varies depending on the Outlook client.
Outlook on the web and the new Outlook on Windows
Classic Outlook on Windows
Outlook on Mac
Outlook on mobile devices
Note
Your online-meeting add-in must meet certain requirements to include the Join and Chat buttons in Outlook on the web, on Mac, on Android, on iOS, and in the new Outlook on Windows. The Join and Chat buttons aren't supported in classic Outlook on Windows. For more information, see Implement the Join and Chat buttons.
Implement the Join and Chat buttons
The Join and Chat buttons only appear in the meeting UI if:
- The online-meeting add-in is published to Microsoft Marketplace. Line-of-business add-ins aren't supported.
- The add-in is registered.
- The meeting participant is using Outlook on the web, on Mac, on Android, on iOS, or the new Outlook on Windows.
- Chat button only: The chat URL in the meeting body must be appended with the
owa-chat=1query parameter.
Register your online-meeting template
To register your online-meeting add-in, once you've published your add-in to Microsoft Marketplace, create a GitHub issue using the following guidance. We'll contact you to coordinate a registration timeline.
- Create a new GitHub issue.
- Set the Title of the new issue to "Outlook: Register the online-meeting template for my-service", replacing
my-servicewith your service name. - In the issue body, replace the existing text with the following:
- The asset ID of your published add-in.
- The string you set in the
newBodyor similar variable from the Implement adding online meeting details section earlier in this article.
- Click Submit new issue.
Add support for the Chat button
To add support for the Chat button, in your JavaScript code, you must include a URL in the meeting body that includes the owa-chat=1 query parameter. The following is an example.
'Chat with meeting participants'
Automatically provide post-meeting resources and updates to attendees
After a meeting ends, the organizer and attendees often need access to important resources such as video recordings or meeting transcripts. If available, your online-meeting add-in can automatically update the meeting invite with these resources, making them easily accessible to all participants.
This section outlines how to use the Microsoft Graph API to update a calendar item with post-meeting resources. The updated content of a meeting will be reflected in the calendars of the organizer and the attendees. Additionally, an update will be sent to the attendees.
This implementation requires the following:
- An access token to make Microsoft Graph API calls. For guidance, see Use the Microsoft Graph REST API from an Outlook add-in.
- An indicator to your add-in when a meeting scheduled with your online-meeting add-in has ended.
- Access to a meeting's Exchange ID and the ID assigned by the add-in.
- Access to the necessary resources that will be added to the meeting.
- Access to the meeting instance created by the organizer. Changes must be made to the organizer's meeting instance to propagate to the attendees' meeting instance.
- When a meeting ends, configure your add-in to fetch the resources that will be added to the meeting object.
- Use the Microsoft Graph API to get the organizer's meeting instance. Ensure that the
bodyproperty is included in the request. For information on the API, see Get event. - Update the body of the meeting with the applicable meeting resources. For information on the API, see Update event.
Important
When making changes to the body property of a meeting, make sure to preserve the online meeting blob. Removing the meeting blob from the body disables the online-meeting functionality.
Once the meeting resources have been added to the meeting, an update is sent to the attendees. The changes are also reflected in the calendar instances of the organizer and the attendees.
The following is an example of how to update the meeting body with a link to a video recording.
const options = {
authProvider,
};
const client = Client.init(options);
// Get the body of the meeting.
const currentEvent = await client.api('/users/{organizerId}/events/{meetingId}')
.select('body')
.get();
const existingBody = currentEvent.body.content;
// Update the body with a link to a video recording.
const meetingResources = `
Meeting summary
The team discussed monthly sales targets for Fabrikam. Current market conditions were discussed. A follow-up meeting will be scheduled to finalize revenue goals for the quarter.
View recording
`;
const updatedBody = existingBody + meetingResources;
const updatedEvent = {
body: {
contentType: 'html',
content: updatedBody
}
};
// Update the event with the new body content.
await client.api('/users/{organizerId}/events/{meetingId}')
.update(updatedEvent);
Available APIs
The following APIs are available for this feature.
- Appointment Organizer APIs
- Office.context.mailbox.item.body (Body.getAsync, Body.setAsync)
- Office.context.mailbox.item.end (Time)
- Office.context.mailbox.item.loadCustomPropertiesAsync (CustomProperties)
- Office.context.mailbox.item.location (Location)
- Office.context.mailbox.item.optionalAttendees (Recipients)
- Office.context.mailbox.item.requiredAttendees (Recipients)
- Office.context.mailbox.item.start (Time)
- Office.context.mailbox.item.subject (Subject)
- Office.context.roamingSettings (RoamingSettings)
- Handle auth flow
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
#919191or 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
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins