Office.NotificationMessages interface
The NotificationMessages object is returned as the notificationMessages property of an item.
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Methods
| add |
Adds a notification to an item. There are a maximum of 5 notifications per message. Setting more will return a |
| add |
Adds a notification to an item. There are a maximum of 5 notifications per message. Setting more will return a |
| get |
Returns all keys and messages for an item. |
| get |
Returns all keys and messages for an item. |
| remove |
Removes a notification message for an item. |
| remove |
Removes a notification message for an item. |
| replace |
Replaces a notification message that has a given key with another message. If a notification message with the specified key doesn't exist, |
| replace |
Replaces a notification message that has a given key with another message. If a notification message with the specified key doesn't exist, |
Method Details
addAsync(key, JSONmessage, options, callback)
Adds a notification to an item.
There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.
addAsync(key: string, JSONmessage: NotificationMessageDetails, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
A developer-specified key used to reference this notification message. Developers can use it to modify this message later. It can't be longer than 32 characters.
- JSONmessage
- Office.NotificationMessageDetails
A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object.
- options
- Office.AsyncContextOptions
An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Important:
Only one notification of type InsightMessage is allowed per add-in. Attempting to add more will throw an error.
In modern Outlook on the web, you can add an
InsightMessagenotification only in Compose mode.Only the
InformationalMessagetype is supported in Outlook on Android and on iOS.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
message: "Progress indicator with id = " + id
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Non-persistent informational notification message with id = " + id,
icon: "icon1",
persistent: false
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Persistent informational notification message with id = " + id,
icon: "icon1",
persistent: true
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Adds an error notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.ErrorMessage,
message: "Error notification message with id = " + id
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
addAsync(key, JSONmessage, callback)
Adds a notification to an item.
There are a maximum of 5 notifications per message. Setting more will return a NumberOfNotificationMessagesExceeded error.
addAsync(key: string, JSONmessage: NotificationMessageDetails, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
A developer-specified key used to reference this notification message. Developers can use it to modify this message later. It can't be longer than 32 characters.
- JSONmessage
- Office.NotificationMessageDetails
A JSON object that contains the notification message to be added to the item. It contains a NotificationMessageDetails object.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Important:
Only one notification of type InsightMessage is allowed per add-in. Attempting to add more will throw an error.
In modern Outlook on the web, you can add an
InsightMessagenotification only in Compose mode.Only the
InformationalMessagetype is supported in Outlook on Android and on iOS.
getAllAsync(options, callback)
Returns all keys and messages for an item.
getAllAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<NotificationMessageDetails[]>) => void): void;Parameters
- options
- Office.AsyncContextOptions
An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.
- callback
-
(asyncResult: Office.AsyncResult<Office.NotificationMessageDetails[]>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The value property of the result is an array of NotificationMessageDetails objects.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.log(asyncResult.error.message);
return;
}
console.log(asyncResult.value);
});
getAllAsync(callback)
Returns all keys and messages for an item.
getAllAsync(callback?: (asyncResult: Office.AsyncResult<NotificationMessageDetails[]>) => void): void;Parameters
- callback
-
(asyncResult: Office.AsyncResult<Office.NotificationMessageDetails[]>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The value property of the result is an array of NotificationMessageDetails objects.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
removeAsync(key, options, callback)
Removes a notification message for an item.
removeAsync(key: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
The key for the notification message to remove.
- options
- Office.AsyncContextOptions
An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);
removeAsync(key, callback)
Removes a notification message for an item.
removeAsync(key: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
The key for the notification message to remove.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
replaceAsync(key, JSONmessage, options, callback)
Replaces a notification message that has a given key with another message.
If a notification message with the specified key doesn't exist, replaceAsync will add the notification.
replaceAsync(key: string, JSONmessage: NotificationMessageDetails, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
The key for the notification message to replace. It can't be longer than 32 characters.
- JSONmessage
- Office.NotificationMessageDetails
A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object.
- options
- Office.AsyncContextOptions
An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.replaceAsync(
id,
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Notification message with id = " + id + " has been replaced with an informational message.",
icon: "icon2",
persistent: false
},
handleResult);
replaceAsync(key, JSONmessage, callback)
Replaces a notification message that has a given key with another message.
If a notification message with the specified key doesn't exist, replaceAsync will add the notification.
replaceAsync(key: string, JSONmessage: NotificationMessageDetails, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;Parameters
- key
-
string
The key for the notification message to replace. It can't be longer than 32 characters.
- JSONmessage
- Office.NotificationMessageDetails
A JSON object that contains the new notification message to replace the existing message. It contains a NotificationMessageDetails object.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for