Skip to content

Interactions

Ask a question, read the matching response, and distinguish responses from delivery acknowledgments.

Ask for a tap, a Yes/No decision, or a short text reply, then read the response through the connected client.

What counts as an interaction

Interactive alerts are available with Pro or Founder Pro. Supported kinds are:

  • tap: records an open or tap. It is not agreement to a separate action.
  • yes_no: asks a specific question with Yes and No responses.
  • text: asks for a text reply, up to 1,000 characters.

Yes/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.

Before sending

Check 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.

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.

Ask 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.

Send a question through MCP

For 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.

For a notification-only question, use agentalerts_send. This sample asks a low-stakes question and has no callback destination:

{
  "activityId": "summary-format-question",
  "surfaces": ["notification"],
  "payload": {
    "title": "Summary preference",
    "summary": "Use a short bullet list?",
    "status": "good"
  },
  "notification": {
    "title": "Summary preference",
    "body": "Would you like this summary as a short bullet list?"
  },
  "interaction": {
    "kind": "yes_no"
  }
}

Keep 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.

Use 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.

Read the answer

Call agentalerts_interaction_status with the exact returned ID:

{
  "interactionId": "REPLACE_WITH_RETURNED_INTERACTION_ID"
}
  • pending: no accepted answer yet. It means neither Yes nor No.
  • responded: inspect responseValue and the matching interaction before proceeding.
  • expired: terminal. Do not interpret it as consent or continue polling.

Poll 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.

The 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.

Keep acknowledgments separate

These are different facts:

  • Service acceptance: APNs accepted an alert for delivery. It does not establish device visibility or a user response.
  • Device acknowledgment: the iPhone confirmed a particular operation. A Live Activity start acknowledgment is not an answer to a question.
  • Interaction response: the service stored the user's response to the matching interaction.
  • Callback acknowledgment: a callback receiver returned HTTP 2xx. It acknowledges receipt of that callback, not user approval or successful completion of the requested task.

Reading an interaction's status does not acknowledge a queue item or consume the answer.

Optional callbacks and local controls

An 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 for access boundaries.

Document 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.

Troubleshooting

  • No interaction ID: inspect the send result. An eligible delivery target is required to create an interaction. not_created is not a pending answer.
  • Immediate expiry: if every interaction-capable delivery fails, the service can expire the interaction rather than leave an unreachable question pending.
  • No response actions: verify the notification surface and matching notification object for yes_no or text, iPhone notification permissions, and current Pro/access readiness.
  • 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.
  • 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.

The 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.