{"document":{"id":"agent-alerts-doc-notifications","kind":"doc","slug":"notifications","title":"Notifications","description":"Send an iPhone notification on its own or with a Live Activity, customize it, and check delivery and response status.","keywords":["Agent Alerts","notifications","push","iPhone","MCP","interactions","permissions","attention"],"updatedAt":"2026-11-12","content":"# Notifications\n\nSend an iPhone notification on its own or with a Live Activity, customize it, and check delivery and response status.\n\nSend 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.\n\n## Before you start\n\nInstall 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](/agent-alerts/docs/remote-mcp).\n\nThe 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.\n\n## Send a notification on its own\n\nFor example:\n\n```text\nSend 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.\n```\n\nThe 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:\n\n```json\n{\n  \"activityId\": \"notification-setup-check\",\n  \"surfaces\": [\"notification\"],\n  \"payload\": {\n    \"title\": \"Setup check\",\n    \"summary\": \"Your notification connection is ready to test.\"\n  },\n  \"notification\": {\n    \"title\": \"Setup check\",\n    \"body\": \"Your notification connection is ready to test.\",\n    \"threadId\": \"setup-checks\"\n  }\n}\n```\n\nThis is an MCP argument example. Webhook and CLI request shapes differ. A notification-only send does not require a Live Activity presentation preset.\n\n## Notify alongside a Live Activity\n\nFor normal Live Activity work, use `agentalerts_publish_live_activity` with one stable `activityKey` for the subject. Its `importance` setting controls attention:\n\n- `persistent` keeps non-approval Live Activity updates quiet. Approval content always includes notification delivery and an interaction.\n- `attention` adds a visible notification.\n- `response_required` is for an approval question and requires Pro.\n\nFor 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](/agent-alerts/blog/keep-one-live-activity-current).\n\n## Customize the message\n\nThe notification object supports:\n\n- `title`, up to 80 characters, and `body`, up to 240 characters. Both are required.\n- `subtitle`, up to 80 characters.\n- `threadId`, up to 128 characters, to group related notifications in Notification Center.\n- `deepLink`, up to 500 characters, to open relevant context. Use a verified destination that the user can access.\n- `interruptionLevel`: `passive`, `active`, or `time-sensitive`.\n\nA 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.\n\n## Request a response\n\nInteractive 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.\n\nA 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](/agent-alerts/docs/responses-and-permissions).\n\n## Delivery, limits, and troubleshooting\n\nA `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.\n\nNotifications 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](/agent-alerts/pricing) for the current plan.\n\n- **`no_targets`:** open Agent Alerts and check the account, notification permission, and device registration.\n- **`partial`:** some delivery attempts failed. Inspect the receipt before retrying.\n- **`quota_limited`:** the original update was not delivered. If `retryable` is false, do not keep resending it.\n- **Accepted, but not visible:** check iOS notification settings, Focus, and Notification Center. Keep the result described as accepted until confirmed on the device.\n\nFor 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](/agent-alerts/docs/alarms).\n","path":"docs/notifications","url":"https://www.andreas.ink/agent-alerts/docs/notifications","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fnotifications&format=markdown"}}