Newer Version Available

This content describes an older version of this product. View Latest

CustomNotification Class

CustomNotification is used to create, configure, and send custom notifications from Apex code.

Namespace

Messaging

Usage

CustomNotification allows two approaches to creating and configuring a custom notification.

Create an instance with the default constructor, and then set notification attributes using the various setter methods.
Create an instance and configure notification parameters at the same time using the parameterized constructor.

Once the custom notification is configured, call send() to send the notification.

Notification Target

The notification target is used by the receiving client application to navigate to an appropriate record or page when a user responds to a notification. For example, when a user is notified that a record was updated, responding to the notification can open the relevant record.

You must specify a target for a notification. The target can be specified using either the targetID or the targetPageRef attribute. Neither attribute is required, but if both are omitted, send() throws an exception. If there’s no natural target for a notification, set the targetID to a dummy value, such as 000000000000000AAA. A dummy value prevents the exception, and also prevents automatic navigation when responding to the notification in the client app.

You can set both targetID and targetPageRef in the same notification. The client app that receives the notification determines which target, if any, to use when responding to the notification.

Before Winter ’21 you could set only a target record (targetID) for a notification. Most client applications expect to find a targetID in the notification payload. If you can’t update a client app to handle notifications that include only a targetPageRef, set the targetID to a dummy value.

Important

Execution Context and Notification Permissions

By default Apex code executes in system mode, and doesn’t require user permissions to send notifications with CustomNotification. However, if your Apex code runs in a user context—for example, by executing anonymous Apex in the Developer Console—the Send Custom Notifications user permission is checked, and send() fails if you don’t have the required permission.

Example

This example Apex class provides a static method for sending a custom notification to a recipient list. Call this method from a trigger, flow, or wherever you want to send a custom notification from Apex.

1public without sharing class CustomNotificationFromApex {
2
3    public static void notifyUsers(Set<String> recipientsIds, String targetId) {
4
5        // Get the Id for our custom notification type
6        CustomNotificationType notificationType = 
7            [SELECT Id, DeveloperName 
8             FROM CustomNotificationType 
9             WHERE DeveloperName='Custom_Notification'];
10        
11        // Create a new custom notification
12        Messaging.CustomNotification notification = new Messaging.CustomNotification();
13
14        // Set the contents for the notification
15        notification.setTitle('Apex Custom Notification');
16        notification.setBody('The notifications are coming from INSIDE the Apex!');
17
18        // Set the notification type and target
19        notification.setNotificationTypeId(notificationType.Id);
20        notification.setTargetId(targetId);
21        
22        // Actually send the notification
23        try {
24            notification.send(recipientsIds);
25        }
26        catch (Exception e) {
27            System.debug('Problem sending notification: ' + e.getMessage());
28        }
29    }
30}

This example uses a hard-coded string, Custom_Notification, as the DeveloperName (also known as the API Name) of a Custom Notification Type. Use your custom notification types in your own code.

CustomNotification.send() can throw an exception, which is handled minimally in this example. Add more substantial error handling to code you plan to use in production.

Note

CustomNotification Constructors

The following are constructors for CustomNotification.

CustomNotification()

Creates a new instance of the Messaging.CustomNotification class.

Signature

public CustomNotification()

CustomNotification(typeId, sender, title, body, targetId, targetPageRef)

Creates an instance of the Messaging.CustomNotification class using the specified parameters. When you use this constructor, you don’t need to call the various setter methods to define the custom notification attributes.

Signature

public CustomNotification(String typeId, String sender, String title, String body, String targetId, String targetPageRef)

Parameters

typeId: Type: String; The ID of the Custom Notification Type being used for the notification.
sender: Type: String; The User ID of the sender of the notification.
title: Type: String; The title of the notification. Maximum characters: 250.
body: Type: String; The body of the notification. Maximum characters: 750.
targetId: Type: String; The Record ID for the target record of the notification.
You must specify either a targetID or a targetPageRef. See Custom Notification Usage.
targetPageRef: Type: String; The PageReference for the navigation target of the notification. To see how to specify the target using JSON, see pageReference Types.
You must specify either a targetID or a targetPageRe. See Custom Notification Usage.

Usage

A client may see a truncated notification title or body depending on the delivery channel or app, and how the Connect API notification parameters are configured. For more information on the trimMessages query parameter, see Notification .

CustomNotification Methods

The following are methods for CustomNotification.

send(users)

Sends a custom notification to the specified users.

Signature

public void send(Set<String> users)

Parameters

users

Type: Set<String>

Required. A set of recipient IDs. Each recipient ID corresponds to a recipient or recipient type that the notification should be sent to. Valid recipient or recipient type values are:

UserId — The notification is sent to this user, if this user is active.
AccountId — The notification is sent to all active users who are members of this account’s Account Team.
This recipient type is valid if account teams are enabled for your org.
Note
OpportunityId — The notification is sent to all active users who are members of this opportunity’s Opportunity Team.
This recipient type is valid if team selling is enabled for your org.
Note
GroupId — The notification is sent to all active users who are members of this group.
QueueId — The notification is sent to all active users who are members of this queue.

pageRef: Type: String; The PageReference for the navigation target of the notification.; Either a targetID or a targetPageRef is required to send a custom notification. See Custom Notification Usage.

Return Value

Type: void

Example

See the Custom Notification Example.

Apex Reference Guide

CustomNotification Class

Namespace

Usage

Example

See Also

CustomNotification Constructors

CustomNotification()

Signature

CustomNotification(typeId, sender, title, body, targetId, targetPageRef)

Signature

Parameters

Usage

CustomNotification Methods

send(users)

Signature

Parameters

Return Value

Example

setNotificationTypeId(id)

Signature

Parameters

Return Value

Example

setTitle(title)

Signature

Parameters

Return Value

Example

setBody(body)

Signature

Parameters

Return Value

Example

setSenderId(id)

Signature

Parameters

Return Value

Example

setTargetId(targetId)

Signature

Parameters

Return Value

Example

setTargetPageRef(pageRef)

Signature

Parameters

Return Value

Example