{"document":{"id":"agent-alerts-doc-interactions","kind":"doc","slug":"interactions","title":"Interactions","description":"Ask a question, read the matching response, and distinguish responses from delivery acknowledgments.","keywords":["Agent Alerts","interactions","responses","approvals","yes_no","text","polling","Pro"],"updatedAt":"2026-11-11","content":"# Interactions\n\nAsk a question, read the matching response, and distinguish responses from delivery acknowledgments.\n\nAsk for a tap, a Yes/No decision, or a short text reply, then read the response through the connected client.\n\n## What counts as an interaction\n\nInteractive alerts are available with Pro or Founder Pro. Supported kinds are:\n\n- `tap`: records an open or tap. It is not agreement to a separate action.\n- `yes_no`: asks a specific question with Yes and No responses.\n- `text`: asks for a text reply, up to 1,000 characters.\n\nYes/No and text requests require the notification surface, even when the same send also includes a Live Activity. Some Live Activity presentations provide response controls too, but their existence does not remove that delivery requirement. An interaction is a send-level request, not a Live Activity template.\n\n## Before sending\n\nCheck `agentalerts_status` if account readiness, Pro access, or permissions are unknown. A token-based interactive connection needs both `publish` and `interact`. An agent token can read only interactions it originated; an OAuth connection reads interactions owned by the linked account.\n\n`billing_reconciliation_pending` is not a final Pro denial. The interactive send can perform bounded server verification. Inspect the actual result rather than repeatedly resending a decision request.\n\nAsk one clear question and identify what the answer will authorize. Make sure notifications are allowed on the iPhone. Do not use an interaction to bypass your AI client's own confirmation or safety requirements.\n\n## Send a question through MCP\n\nFor a semantic approval Live Activity, use the approval content supported by `agentalerts_publish_live_activity`. Read `agentalerts_live_activity_examples` for the exact current request shape.\n\nFor a notification-only question, use `agentalerts_send`. This sample asks a low-stakes question and has no callback destination:\n\n```json\n{\n  \"activityId\": \"summary-format-question\",\n  \"surfaces\": [\"notification\"],\n  \"payload\": {\n    \"title\": \"Summary preference\",\n    \"summary\": \"Use a short bullet list?\",\n    \"status\": \"good\"\n  },\n  \"notification\": {\n    \"title\": \"Summary preference\",\n    \"body\": \"Would you like this summary as a short bullet list?\"\n  },\n  \"interaction\": {\n    \"kind\": \"yes_no\"\n  }\n}\n```\n\nKeep the returned `interactionId`. Expiry defaults to 24 hours. To choose a shorter deadline, supply a future ISO 8601 `expiresAt`; it cannot be more than seven days away.\n\nUse a fresh idempotency key for a new question. Reuse a key only to retry the exact same request, so an earlier answer cannot become permission for a different decision.\n\n## Read the answer\n\nCall `agentalerts_interaction_status` with the exact returned ID:\n\n```json\n{\n  \"interactionId\": \"REPLACE_WITH_RETURNED_INTERACTION_ID\"\n}\n```\n\n- `pending`: no accepted answer yet. It means neither Yes nor No.\n- `responded`: inspect `responseValue` and the matching interaction before proceeding.\n- `expired`: terminal. Do not interpret it as consent or continue polling.\n\nPoll with restraint and stop at a terminal state. The first accepted response wins; a duplicate submission returns the stored response. If the question changes materially, create a new interaction.\n\nThe current remote MCP exposes per-interaction status polling. It does not expose a general read-events feed or an event-acknowledgment tool. Do not substitute an assumed `read-events` or `ack` command for the documented polling flow.\n\n## Keep acknowledgments separate\n\nThese are different facts:\n\n- **Service acceptance:** APNs accepted an alert for delivery. It does not establish device visibility or a user response.\n- **Device acknowledgment:** the iPhone confirmed a particular operation. A Live Activity start acknowledgment is not an answer to a question.\n- **Interaction response:** the service stored the user's response to the matching interaction.\n- **Callback acknowledgment:** a callback receiver returned HTTP 2xx. It acknowledges receipt of that callback, not user approval or successful completion of the requested task.\n\nReading an interaction's status does not acknowledge a queue item or consume the answer.\n\n## Optional callbacks and local controls\n\nAn interaction can reference pre-registered callback destination IDs. Use only known, approved destinations. The receiver must verify the signed callback using the exact raw request body and deduplicate deliveries. Callback delivery is separate from the stored response, so inspect `callbackStatus` independently. See [Responses and permissions](/agent-alerts/docs/responses-and-permissions) for access boundaries.\n\nDocument cards can also offer local carousel and checkbox controls. Those controls change the Live Activity's local display. They do not automatically submit a durable interaction response, edit the source document, or authorize your agent to act.\n\n## Troubleshooting\n\n- **No interaction ID:** inspect the send result. An eligible delivery target is required to create an interaction. `not_created` is not a pending answer.\n- **Immediate expiry:** if every interaction-capable delivery fails, the service can expire the interaction rather than leave an unreachable question pending.\n- **No response actions:** verify the notification surface and matching notification object for `yes_no` or `text`, iPhone notification permissions, and current Pro/access readiness.\n- **Cannot read an ID:** use the exact returned ID and the originating token or correct linked account. Do not guess IDs or switch accounts to bypass access restrictions.\n- **Expired before answering:** ask again only if the decision is still needed, using a new interaction. Do not escalate to an alarm without the user's explicit request.\n\nThe Homebrew Swift CLI and remote MCP have different command sets. The Swift CLI implementation includes phone-approval hooks, but that does not establish a general `interaction status` or `interaction wait` command. Use the remote MCP flow above for direct polling and consult the current CLI README for hook support.\n","path":"docs/interactions","url":"https://www.andreas.ink/agent-alerts/docs/interactions","markdownUrl":"https://www.andreas.ink/api/agent-alerts/content?path=docs%2Finteractions&format=markdown"}}