Push

The server sends pushes through the Apple Push Notification service (APNs) to the devices of an account. A device registers its tokens with PUT /v1/devices/{device_id}. See REST API.

Overview of the pushes#

A device with the platform watchos gets the topic of the watch app, if the server has a bundle ID for it.

The server sends a push after it sends the HTTP response. A push does not make a request slower.

Who gets which notification#

Each notification goes to each device of the account that has an apns_token.

Task notifications#

event is task.created, task.updated, or task.deleted.

Visible#

{
  "aps": {
    "alert": { "title": "Claude Code", "subtitle": "Task done", "body": "Add dark mode support" },
    "sound": "default",
    "thread-id": "key_01jb2k3v9d",
    "category": "TASK",
    "interruption-level": "active"
  },
  "event": "task.updated",
  "task_id": "tsk_01jb2m9x4e7q",
  "key_id": "key_01jb2k3v9d"
}

Silent#

{ "aps": { "content-available": 1 }, "event": "task.updated", "task_id": "tsk_...", "key_id": "key_..." }

Message notifications#

A notify_user call sends this notification. It has no collapse ID.

{
  "aps": {
    "alert": { "title": "Claude Code", "subtitle": "Approve the deploy", "body": "The build is ready." },
    "sound": "default",
    "thread-id": "key_01jb2k3v9d",
    "category": "MESSAGE",
    "interruption-level": "active"
  },
  "event": "message",
  "key_id": "key_01jb2k3v9d",
  "task_id": "tsk_01jb2m9x4e7q"
}

• alert.subtitle is the title that the agent gives. alert.body is the body that the agent gives.
• task_id is there only if the agent gave one. If that task is urgent, interruption-level is time-sensitive.

Question notifications#

New question#

{
  "aps": {
    "alert": { "title": "Claude Code", "subtitle": "Question", "body": "Deploy to production now?" },
    "sound": "default",
    "thread-id": "key_01jb2k3v9d",
    "category": "QUESTION_CONFIRM",
    "interruption-level": "time-sensitive",
    "mutable-content": 1
  },
  "event": "question.created",
  "question_id": "qst_01jb2n4r8t",
  "kind": "confirm",
  "options": ["Yes", "No"],
  "task_id": "tsk_01jb2m9x4e7q",
  "key_id": "key_01jb2k3v9d"
}

The app answers with POST /v1/questions/{question_id}/answer. See REST API.

Status change#

When a question is answered, expired, or cancelled, the server sends a silent notification with the same collapse ID. Each device then removes the delivered notification of that question.

{ "aps": { "content-available": 1 }, "event": "question.updated", "question_id": "qst_...", "key_id": "key_..." }

Live Activity#

The ActivityKit attributes type name is TaskActivityAttributes. The JSON keys below are exact, because ActivityKit decodes them with the default JSONDecoder.

Attributes:

{ "taskID": "tsk_01jb2m9x4e7q", "keyLabel": "Claude Code" }

Content state:

{
  "title": "Add dark mode support",
  "status": "in_progress",
  "progress": 40,
  "note": "Waiting for you",
  "updatedAt": 1760112300.9,
  "question": { "id": "qst_01jb2n4r8t", "prompt": "Deploy to production now?", "kind": "confirm", "options": ["Yes", "No"] }
}

• progress and note can be null.
• question is the oldest pending question of the task. It is null when the task has no pending question.

The server sends these pushes when the account setting live_activities is true.

An update goes at once when the activity got none in the last 5 seconds. Else the server sends one update with the latest state of the task when those 5 seconds end. Thus an agent that sends many progress ticks gives one push in 5 seconds for each task, and the last change is never lost. Each Live Activity push has the APNs priority 10, because a push with the priority 5 can wait for a long time on a locked device. | The task becomes done or cancelled, or the task or its key is deleted | end, with the final content state and a dismissal date 15 minutes later |

Each payload has aps.timestamp, aps.event (start, update, or end), and aps.content-state. A start and an update also have stale-date (30 minutes after the push: the system then shows the activity as stale) and relevance-score (100 when the task has a pending question, 75 when the task is in_progress, else 50; the activity with the highest score goes first). A start also has attributes-type, attributes, and an alert with the key label as title and the task title as body, because ActivityKit needs one. An end also has dismissal-date.

Widget reload#

A device that registers a widget_push_token gets a WidgetKit push when a task or a question of the account changes. WidgetKit then reloads the widget timelines. The push carries no task data.

{ "aps": { "content-changed": true } }

• A device gets one widget push in 15 seconds at most.
• If more changes come in those 15 seconds, the device gets one more push when the 15 seconds end. Thus the last change is not lost.
• The system also limits how often it delivers these pushes.

Tokens that are not valid#

If APNs answers 410, or 400 with the reason BadDeviceToken, the server sets that token of the device to null, or removes that Live Activity registration. The app registers a new token with the next PUT.