Skip to content

Notifications

Send an iPhone notification on its own or with a Live Activity, customize it, and check delivery and response status.

Send a notification when an update needs attention on your iPhone. Use a quiet Live Activity for routine progress, and reserve notifications for the findings, blockers, or finished results you agreed to receive.

Before you start

Install Agent Alerts, sign in, and allow notifications when prompted. If permission was declined, review Agent Alerts in iPhone Settings and enable the notification options you want. Open the app to refresh its device registration, then connect your agent using remote MCP.

The app's notification permission and its Live Activity and alarm permissions are separate. Notification appearance and sound also depend on iOS settings, including Focus and notification delivery settings.

Send a notification on its own

For example:

Send one Agent Alerts notification to my iPhone titled “Setup check” with the message “Your notification connection is ready to test.” Do not start a Live Activity. Tell me the returned delivery status, and I will confirm it on my phone.

The native MCP tool for explicit surface routing is agentalerts_send. Set surfaces to ["notification"] and include the required notification object. The tool also requires an activity ID and payload even for a notification-only request:

{
  "activityId": "notification-setup-check",
  "surfaces": ["notification"],
  "payload": {
    "title": "Setup check",
    "summary": "Your notification connection is ready to test."
  },
  "notification": {
    "title": "Setup check",
    "body": "Your notification connection is ready to test.",
    "threadId": "setup-checks"
  }
}

This is an MCP argument example. Webhook and CLI request shapes differ. A notification-only send does not require a Live Activity presentation preset.

Notify alongside a Live Activity

For normal Live Activity work, use agentalerts_publish_live_activity with one stable activityKey for the subject. Its importance setting controls attention:

  • persistent keeps non-approval Live Activity updates quiet. Approval content always includes notification delivery and an interaction.
  • attention adds a visible notification.
  • response_required is for an approval question and requires Pro.

For explicit multi-surface sends, use agentalerts_send and include both live_activity and notification in surfaces, with the required content for each. See keeping one Live Activity current.

Customize the message

The notification object supports:

  • title, up to 80 characters, and body, up to 240 characters. Both are required.
  • subtitle, up to 80 characters.
  • threadId, up to 128 characters, to group related notifications in Notification Center.
  • deepLink, up to 500 characters, to open relevant context. Use a verified destination that the user can access.
  • interruptionLevel: passive, active, or time-sensitive.

A grouping ID groups messages; it does not guarantee that an earlier notification will be replaced. Interruption level is a request to iOS, not a promise to bypass the user's settings. The tool does not offer a critical-alert level, arbitrary sound selection, or AlarmKit scheduling through this object.

Request a response

Interactive alerts are a Pro feature. Yes/No and text responses require notification delivery and a real interaction request. Keep the returned interactionId and poll agentalerts_interaction_status through the originating connection.

A delivered notification, tap, pending response, or expired question does not establish Yes/No approval. Act only on the explicit answer to the intended question. See responses and permissions.

Delivery, limits, and troubleshooting

A sent result or successful target count reports APNs acceptance, not proof that a banner appeared or someone read it. Inspect the requested surfaces, deliveryStage, failure details, and any nextAction. Confirm the first test on your iPhone.

Notifications and Live Activities share the delivered-alert allowance. Free accounts have 350 delivered-alert events per UTC day. Pro accounts, including lifetime Pro, have 3,500. Sending both surfaces as one event counts as one delivered-alert event when accepted. Review pricing for the current plan.

  • no_targets: open Agent Alerts and check the account, notification permission, and device registration.
  • partial: some delivery attempts failed. Inspect the receipt before retrying.
  • quota_limited: the original update was not delivered. If retryable is false, do not keep resending it.
  • Accepted, but not visible: check iOS notification settings, Focus, and Notification Center. Keep the result described as accepted until confirmed on the device.

For recurring checks, use your agent's scheduler and agree on when a notification is worth sending. Connecting Agent Alerts does not start monitoring. For a timed alarm rather than an ordinary notification, see alarms.