{"document":{"id":"agent-alerts-doc-widgets","kind":"doc","slug":"widgets","title":"Widgets","description":"Place Home Screen and Lock Screen snapshot widgets, publish updates, and understand refresh behavior.","keywords":["Agent Alerts","widgets","Home Screen","Lock Screen","snapshot","WidgetKit"],"updatedAt":"2026-11-11","content":"# Widgets\n\nPlace Home Screen and Lock Screen snapshot widgets, publish updates, and understand refresh behavior.\n\nKeep a recent report on your Home Screen or Lock Screen, and use Live Activities for richer dashboard layouts.\n\n## Choose the right kind of widget\n\nSnapshot widgets show the latest received widget report. Add them through the iPhone's widget gallery. Home Screen sizes are small and medium; Lock Screen options are inline, circular, and rectangular.\n\nA Live Activity appears on the Lock Screen and, on supported iPhones, Dynamic Island. Its lifecycle and layout are separate from a placed snapshot widget. Use [Builder layouts](/agent-alerts/docs/builder-layouts) to customize a Live Activity through JSON.\n\n## Add a snapshot widget\n\n1. Install Agent Alerts, finish onboarding, and sign in to the account connected to your publishing client. Open the app and let device registration finish.\n2. To add a Home Screen widget, touch and hold the Home Screen, open its widget picker, search for Agent Alerts, and choose small or medium.\n3. For a Lock Screen widget, customize the Lock Screen and choose Agent Alerts from the widget picker. Choose a size that fits the available space.\n4. Send a widget update from a connected client, then check the placed widget on the iPhone.\n\nThe current snapshot widget shows the latest received report. It does not offer a per-instance report picker. Sending different widget IDs does not make each placed copy display an independently selected report.\n\n## Publish a widget snapshot\n\nUse the advanced remote MCP tool, `agentalerts_send`, for widget delivery. Add `widget` to `surfaces` and include a matching `widget` object with `widgetId` and `snapshot`. The snapshot uses the report content fields, such as `title`, `summary`, `status`, and metric fields.\n\nThis illustrative widget-only request does not start a Live Activity or request a visible notification:\n\n```json\n{\n  \"activityId\": \"release-summary\",\n  \"surfaces\": [\"widget\"],\n  \"payload\": {\n    \"title\": \"Release checks\",\n    \"summary\": \"Five checks passed.\",\n    \"status\": \"good\"\n  },\n  \"widget\": {\n    \"widgetId\": \"release-summary\",\n    \"snapshot\": {\n      \"title\": \"Release checks\",\n      \"summary\": \"Five checks passed.\",\n      \"status\": \"good\",\n      \"sourceName\": \"Release workflow\",\n      \"primaryLabel\": \"Checks passed\",\n      \"primaryValue\": \"5\"\n    }\n  }\n}\n```\n\nReplace sample values with observed results. Use small, non-secret content because widgets can be visible while the phone is locked. The publishing connection needs the appropriate sending access; `agentalerts_status` reports linked-account readiness and limits.\n\nThe normal `agentalerts_publish_live_activity` tool is for Live Activities. Use the advanced send tool when you explicitly need a widget surface. A widget refresh does not create a recurring data collection schedule.\n\n## Refresh and troubleshooting\n\nThe app stores an incoming snapshot and asks WidgetKit to reload. iOS controls refresh timing and can combine or delay reload requests. A successful service send is not proof that a placed widget has repainted.\n\n- **No widget appears:** add it through the iPhone's widget picker.\n- **Old or sample content:** open Agent Alerts, check the connected account and device registration, and send a fresh widget snapshot. The widget shows preview content until a snapshot is available.\n- **Wrong report:** the placed widget uses the latest received snapshot, including reports sent with another widget ID.\n- **Missing update:** check `status`, `failureCode`, `nextAction`, and target counts in the send response. Confirm that `surfaces` includes `widget` and its object contains both `widgetId` and `snapshot`.\n- **Different layout than expected:** snapshot widgets have fixed size-specific layouts. A custom `builderSpec` controls Live Activity layouts, not the placed Home Screen widget's view hierarchy.\n\nSee [Troubleshooting](/agent-alerts/docs/troubleshooting) for connection and delivery checks.\n","path":"docs/widgets","url":"https://www.andreas.ink/agent-alerts/docs/widgets","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Fwidgets&format=markdown"}}