[office-js][office-js-preview] (Outlook) Clarify the description of the Office.NotificationMessageDetails.icon property (DefinitelyTyped#72799)

Author: samantharamon

types/office-js-preview/index.d.ts

@@ -10432,7 +10432,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Organizer
          *
-         * **Important**: This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
+         * - This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          */
         notificationMessages: NotificationMessages;
@@ -12009,7 +12014,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Attendee
          *
-         * **Important**: This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
+         * - This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          */
         notificationMessages: NotificationMessages;
@@ -15363,7 +15373,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
          *
-         * **Important**: Only the `getAllAsync` method of the NotificationMessages object is supported.
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
+         * - Only the `getAllAsync` method of the NotificationMessages object is supported.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -16385,6 +16400,9 @@ declare namespace Office {
          *
          * **Important**:
          *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
          * - Only the `getAllAsync` method of the NotificationMessages object is supported.
          */
         notificationMessages: NotificationMessages;
@@ -18815,6 +18833,9 @@ declare namespace Office {
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
+         *
+         * **Important**: To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -20553,6 +20574,9 @@ declare namespace Office {
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Read
+         *
+         * **Important**: To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -21506,6 +21530,9 @@ declare namespace Office {
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
+     *
+     * **Important**: To learn about the different types of notification messages you can implement, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
      */
     interface NotificationMessageDetails {
         /**
@@ -21532,13 +21559,27 @@ declare namespace Office {
          */
         type: MailboxEnums.ItemNotificationMessageType | string;
         /**
-         * A reference to an icon that's defined in the manifest. It appears in the infobar area.
-         * It's applicable if the type is `InformationalMessage`, and is required if the type is `InsightMessage`.
-         * Specifying this parameter for an unsupported type results in an exception.
+         * A reference to a custom icon that's defined in the manifest. The icon appears before the notification message in the infobar area.
+         * An icon must be specified for `InformationalMessage` and `InsightMessage` notifications.
          *
          * @remarks
          *
-         * **Important**: Currently, the custom icon is only displayed in classic Outlook on Windows.
+         * **Important**:
+         *
+         * - Currently, the custom icon is only displayed in classic Outlook on Windows.
+         *
+         * - A custom icon is only supported in `InformationalMessage` and `InsightMessage` notifications. Specifying an icon for other notification
+         * types results in an exception.
+         *
+         * - If your add-in uses the {@link https://learn.microsoft.com/office/dev/add-ins/develop/add-in-manifests | add-in only manifest}, the icon
+         * must be specified in the {@link https://learn.microsoft.com/javascript/api/manifest/images | Images} element of the
+         * {@link https://learn.microsoft.com/javascript/api/manifest/resources | Resources} section of the manifest.
+         *
+         * - If your add-in uses the {@link https://learn.microsoft.com/office/dev/add-ins/develop/unified-manifest-overview | unified manifest for Microsoft 365},
+         * you can't currently customize the icon of an `InformationalMessage` or `InsightMessage` notification. The notification uses the first image specified in the
+         * {@link https://learn.microsoft.com/microsoft-365/extensibility/schema/extension-common-icon | "icons"} array of the first
+         * {@link https://learn.microsoft.com/microsoft-365/extensibility/schema/extension-common-custom-group-controls-item | extensions.ribbons.tabs.groups.controls} object
+         * of the manifest. Although this is the case, you must still specify a string in the `icon` property (for example, "icon-16").
          */
         icon?: string;
         /**
@@ -21578,6 +21619,9 @@ declare namespace Office {
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
+     *
+     * **Important**: To learn about the different types of notification messages you can implement, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
      */
     interface NotificationMessages {
         /**

types/office-js/index.d.ts

@@ -10367,7 +10367,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Organizer
          *
-         * **Important**: This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         * 
+         * - This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          */
         notificationMessages: NotificationMessages;
@@ -11935,7 +11940,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Appointment Attendee
          *
-         * **Important**: This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
+         * - This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see
          * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-mobile-apis | Outlook JavaScript APIs supported in Outlook on mobile devices}.
          */
         notificationMessages: NotificationMessages;
@@ -15102,7 +15112,12 @@ declare namespace Office {
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
          *
-         * **Important**: Only the `getAllAsync` method of the NotificationMessages object is supported.
+         * **Important**:
+         *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
+         * - Only the `getAllAsync` method of the NotificationMessages object is supported.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -16103,6 +16118,9 @@ declare namespace Office {
          *
          * **Important**:
          *
+         * - To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
+         *
          * - Only the `getAllAsync` method of the NotificationMessages object is supported.
          */
         notificationMessages: NotificationMessages;
@@ -18520,6 +18538,9 @@ declare namespace Office {
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Compose
+         *
+         * **Important**: To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -20246,6 +20267,9 @@ declare namespace Office {
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
          *
          * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Message Read
+         *
+         * **Important**: To learn about the different types of notification messages you can implement, see
+         * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
          */
         notificationMessages: NotificationMessages;
         /**
@@ -21109,6 +21133,9 @@ declare namespace Office {
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
+     *
+     * **Important**: To learn about the different types of notification messages you can implement, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
      */
     interface NotificationMessageDetails {
         /**
@@ -21135,13 +21162,27 @@ declare namespace Office {
          */
         type: MailboxEnums.ItemNotificationMessageType | string;
         /**
-         * A reference to an icon that's defined in the manifest. It appears in the infobar area.
-         * It's applicable if the type is `InformationalMessage`, and is required if the type is `InsightMessage`.
-         * Specifying this parameter for an unsupported type results in an exception.
+         * A reference to a custom icon that's defined in the manifest. The icon appears before the notification message in the infobar area.
+         * An icon must be specified for `InformationalMessage` and `InsightMessage` notifications.
          *
          * @remarks
          *
-         * **Important**: Currently, the custom icon is only displayed in classic Outlook on Windows.
+         * **Important**:
+         *
+         * - Currently, the custom icon is only displayed in classic Outlook on Windows.
+         *
+         * - A custom icon is only supported in `InformationalMessage` and `InsightMessage` notifications. Specifying an icon for other notification
+         * types results in an exception.
+         *
+         * - If your add-in uses the {@link https://learn.microsoft.com/office/dev/add-ins/develop/add-in-manifests | add-in only manifest}, the icon
+         * must be specified in the {@link https://learn.microsoft.com/javascript/api/manifest/images | Images} element of the
+         * {@link https://learn.microsoft.com/javascript/api/manifest/resources | Resources} section of the manifest.
+         *
+         * - If your add-in uses the {@link https://learn.microsoft.com/office/dev/add-ins/develop/unified-manifest-overview | unified manifest for Microsoft 365},
+         * you can't currently customize the icon of an `InformationalMessage` or `InsightMessage` notification. The notification uses the first image specified in the
+         * {@link https://learn.microsoft.com/microsoft-365/extensibility/schema/extension-common-icon | "icons"} array of the first
+         * {@link https://learn.microsoft.com/microsoft-365/extensibility/schema/extension-common-custom-group-controls-item | extensions.ribbons.tabs.groups.controls} object
+         * of the manifest. Although this is the case, you must still specify a string in the `icon` property (for example, "icon-16").
          */
         icon?: string;
         /**
@@ -21181,6 +21222,9 @@ declare namespace Office {
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions | Minimum permission level}**: **read item**
      *
      * **{@link https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points | Applicable Outlook mode}**: Compose or Read
+     *
+     * **Important**: To learn about the different types of notification messages you can implement, see
+     * {@link https://learn.microsoft.com/office/dev/add-ins/outlook/notifications | Create notifications for your Outlook add-in}.
      */
     interface NotificationMessages {
         /**