Notification Actions

Actions

Read and act on the device's notifications

Access these methods through agent.actions. They need the optional Notification access permission on the device and an app version newer than 3.8.0. Without the permission both methods resolve with an error instead of throwing.

`getNotifications()`

TypeScript

getNotifications(options?: { includeImages?: boolean }): Promise<NotificationsResult>

Returns every active notification, newest first, with its full details: identity (key, id, tag, package, app name), timing and flags, channel, category and ranking, all text fields (title, text, big text, sub text, text lines, messaging-style messages), progress, the remaining plain extras, which intents it carries, and its actions including inline-reply inputs. With includeImages the large icon and big picture are added as base64 PNG.

Parameters

Name	Type	Description
`options.includeImages?`	`boolean`	Include largeIcon / picture as base64 PNG (default false — keeps the result small)

Returns

Promise<{ accessGranted: boolean; notifications: DeviceNotification[]; error?: string }>accessGranted is false (with an error) when Notification access isn't granted

Examples

TypeScript

const { accessGranted, notifications } = await agent.actions.getNotifications();
if (!accessGranted) throw new Error("Grant Notification access first");
for (const n of notifications) {
  console.log(n.appName, n.title, n.text, n.actions.map((a) => a.title));
}

Find an OTP from a package

TypeScript

const { notifications } = await agent.actions.getNotifications();
const sms = notifications.find((n) => n.packageName === "com.google.android.apps.messaging");
const otp = sms?.text?.match(/\b\d{6}\b/)?.[0];

`actOnNotification()`

TypeScript

actOnNotification(notification: DeviceNotification | string, action?: NotificationAction): Promise<{ success: boolean; error?: string }>

Performs anything a user can do with a notification: open it (its content intent — it is cleared afterwards if it auto-cancels), press one of its actions (by index or title, with replyText for inline-reply actions), dismiss it, or snooze it.

Parameters

Name	Type	Description
`notification`	`DeviceNotification \| string`	An item from getNotifications(), or its key
`action?`	`NotificationAction`	{ type: 'click' } (default) \| { type: 'action', index?: number, title?: string, replyText?: string } \| { type: 'dismiss' } \| { type: 'snooze', durationMs: number }

Returns

Promise<{ success: boolean; error?: string }>error explains a failure (not found, no such action, not dismissible, no access…)

Examples

Open a notification

TypeScript

const { notifications } = await agent.actions.getNotifications();
await agent.actions.actOnNotification(notifications[0]);

Reply inline

TypeScript

const chat = notifications.find((n) => n.actions.some((a) => a.isReply));
await agent.actions.actOnNotification(chat, { type: "action", title: "Reply", replyText: "On my way" });

Dismiss or snooze

TypeScript

await agent.actions.actOnNotification(n.key, { type: "dismiss" });
await agent.actions.actOnNotification(n.key, { type: "snooze", durationMs: 10 * 60 * 1000 });