Phone

Mentra Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.There is currently no way to distribute a miniapp built with the Miniapp SDK. In a future release, developers will upload miniapps through the Mentra Developer Console, and users will download them from the Mentra Miniapp Store. Neither service supports Miniapp SDK distribution in MentraOS 3.0.Only use the Miniapp SDK if you are comfortable with these limitations.Developing on Mentra Live? We recommend using the Mentra Bluetooth SDK.The developer tools are available in the Mentra App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at [email protected].

session.phone reports state from the user’s phone: notifications as they post, calendar events, and the phone’s own battery. Each concern is its own sub-module. Register a handler and the events start arriving.

src/background/index.ts

session.phone.notifications.on((data) => {
  session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `${data.app}: ${data.title}`}]);
});

Notifications need the READ_NOTIFICATIONS permission and calendar events need the CALENDAR permission, both declared in your manifest. Phone battery needs no permission.

Notifications

session.phone.notifications.on() fires when a notification posts on the phone.

session.phone.notifications.on((data) => {
  // data: PhoneNotificationData
});

Each event is a PhoneNotificationData:

Field	Type	Notes
`notificationId`	`string`	Stable id from the phone’s notification listener.
`app`	`string`	Human app name (e.g. `"Messages"`).
`title`	`string`	The notification title.
`content`	`string`	The notification body.
`priority`	`string`	Android priority string; empty on iOS.
`timestamp`	`number`	Unix ms timestamp.
`packageName`	`string`	Reverse-DNS package/bundle id of the originating app.

Dismissals

session.phone.notifications.onDismissed() fires when the user swipes away or clears a notification.

session.phone.notifications.onDismissed((data) => {
  // data: NotificationDismissedData
});

Each event is a NotificationDismissedData:

Field	Type	Notes
`notificationId`	`string`	Same id as the matching post event from `notifications.on(...)`.
`notificationKey`	`string?`	Android NotificationKey. More stable than `notificationId` across reposts.
`packageName`	`string?`	Reverse-DNS package/bundle id of the originating app.
`timestamp`	`number`	Unix ms timestamp of the dismissal.

onDismissed is Android only. iOS does not expose dismiss callbacks to apps (an Apple privacy restriction), so subscribing on iOS succeeds but no events ever fire. The matching notifications.on() post-event works on both platforms.

Calendar

session.phone.calendar.listEvents() reads a current snapshot from all event calendars on the phone. Declare CALENDAR as a required permission; the Mentra App requests access before opening the miniapp.

const result = await session.phone.calendar.listEvents({
  startsAt: new Date(),
  endsAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  limit: 50,
});

The date window may span at most 31 days. limit defaults to 50 and may not exceed 100. The result contains events and a truncated flag. Each event has:

Field	Type	Notes
`id`	`string`	Unique occurrence id, including recurring instances.
`calendarId`	`string`	Id of the source calendar.
`title`	`string`	The event title.
`startsAt`	`string`	ISO 8601 start time. All-day events preserve their calendar timezone offset.
`endsAt`	`string`	ISO 8601 end time. All-day events preserve their calendar timezone offset.
`timezone`	`string?`	The event’s timezone.
`allDay`	`boolean`	Whether it’s an all-day event.
`location`	`string?`	The event location.
`notes`	`string?`	The event notes.
`url`	`string?`	The platform calendar URL field, when available.
`links`	`string[]`	Deduplicated HTTPS links found in URL, location, and notes.

Phone battery

session.phone.onBattery() reports the phone’s battery. It stays flat (not sub-namespaced) because it’s a single event.

session.phone.onBattery((data) => {
  // data: BatteryData
});

Each event is a BatteryData:

Field	Type	Notes
`level`	`number`	Battery level.
`charging`	`boolean`	Whether the phone is charging.

Cleaning up

Every subscription returns an unsubscribe function. The notifications sub-module also has a stop() that tears down every notification subscription at once. Calendar snapshots do not create a subscription.

const off = session.phone.notifications.on(handler);
off();                              // drop this one

session.phone.notifications.stop(); // drop all notification subscriptions

session.phone.notifications.hasPermission tells you whether READ_NOTIFICATIONS is declared in your manifest, and session.phone.calendar.hasPermission tells you whether CALENDAR is declared. Neither tells you whether the user granted the OS prompt. A calendar request rejects with PERMISSION_DENIED if access was later revoked. See Permissions.

Phone Wi-Fi

Use these APIs before a user starts a feature that connects the phone to the glasses hotspot. They concern the phone, independently of session.glasses.requestWifiSetup(), which connects the glasses to a network. Neither method requires a miniapp manifest permission.

const enabled = await session.phone.isWifiEnabled()
if (enabled === false) {
  const result = await session.phone.requestWifiEnable(
    "Live video needs your phone’s Wi-Fi to connect to your glasses.",
  )
  if (result.cancelled || result.enabled === false) return
}
// Continue the requested call/stream. The host handles joining the glasses hotspot.

isWifiEnabled(): Promise<boolean | null> reads the Android radio switch, including when Wi-Fi is on but not connected to a network. On iOS it returns true for an observed Wi-Fi connection and null otherwise: iOS has no public API to read the switch. Unknown does not mean off or that a hotspot join will fail. requestWifiEnable(reason?): Promise<{enabled: boolean | null; cancelled: boolean}> shows a Mentra App prompt with your reason. On Android the action opens the system Wi-Fi panel, falling back to Wi-Fi settings. On iOS it opens the app’s Settings page and explains how to reach Settings → Wi-Fi. No private Settings URLs are used. The miniapp stays mounted; the promise resolves after the user returns and the host rechecks Wi-Fi. Already-enabled Wi-Fi skips the prompt. Cancellation, or a Settings visit exceeding five minutes, returns cancelled: true. The normal short SDK request timeout does not apply while waiting for the user. A null result after returning on iOS lets you attempt the normal system hotspot join; it does not verify the radio is enabled. Call from a user-initiated flow while the Mentra App is active. Concurrent prompts reject with REQUEST_ABORTED. Older hosts or hosts without this capability reject with NOT_IMPLEMENTED. Only prompt automatically when the state is false. When it is null, try the normal hotspot join; call requestWifiEnable() from an explicit recovery action if the connection fails. Neither function switches Wi-Fi on itself, joins an SSID, or requires internet access through Wi-Fi.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Notifications

Dismissals

Calendar

Phone battery

Cleaning up

Phone Wi-Fi

​Notifications

​Dismissals

​Calendar

​Phone battery

​Cleaning up

​Phone Wi-Fi

Notifications

Dismissals

Calendar

Phone battery

Cleaning up

Phone Wi-Fi