Nudges

The nudging system delivers AI-generated coaching moments to your members. Thrive AI Health's coaching pipeline produces a nudge whenever a moment warrants partner-side delivery; a missed action, a trend concern, a recovery opportunity, a morning report, a daily content recommendation, or a scheduled health-action reminder.

Every nudge is published as a single coach.nudge.created event to your configured queue. A target.type discriminator identifies the resource: card (feed cards) or health_action (scheduled action reminders). You own delivery (consent, MLR review, channel execution, fallback logic) and, for card nudges, report back the user's interaction status.

Sequence

The diagram shows the card flow. health_action nudges follow the same delivery pattern but use /v1/users/{user_id}/health-actions/* for fetch/update.

Trigger detectors

The pipeline runs 13 trigger detectors in parallel every 15 minutes. Most produce a card nudge from a behavioral signal (missed actions, trend declines, recovery) or schedule (morning report, daily content recommendation). The action_reminder detector produces a health_action nudge an hour before a scheduled action. For card nudges, the matched trigger is attached to the resulting CoachNudgeCard as trigger_name.

Two internal checks run before a nudge event fires:

• Signal-vs-context: a raw trigger alone is not enough. The pipeline evaluates the signal against the user's current context (e.g. an elevated heart rate during a logged walk is suppressed; the same reading at rest fires).
• Priority-based suppression: nudges are prioritized by Thrive AI Health.

Every nudge that reaches your queue has already cleared both checks.

Event payload; coach.nudge.created

The event uses the standard Thrive AI Health platform envelope (event_id, event_type, signed_at, signature, body); the parsed body JSON carries the discriminator and resource. Partners receive one of two body variants based on a contract-level setting negotiated at onboarding.

Body; Basic variant

Thin event; partners fetch the full resource via the follow-up GET.

{
  "nudge_id": "e259a656-b8bb-45e8-8115-1dded264baf1",
  "created_at": "2026-04-02T14:30:00Z",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "target": {
    "type": "card",
    "id": "b1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "delivery": {
    "urgency": "medium",
    "recommended_channel": "push",
    "notification": {
      "title": "Time for your morning walk",
      "body": "Your scheduled 20-minute walk starts in 5 minutes."
    }
  }
}

Body; Full variant

Includes the complete resource under data.*: partners can render without a follow-up GET.

{
  "nudge_id": "e259a656-b8bb-45e8-8115-1dded264baf1",
  "created_at": "2026-04-02T14:30:00Z",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "target": { "type": "card", "id": "b1b2c3d4-..." },
  "delivery": { "urgency": "high", "recommended_channel": "push", "notification": { "title": "...", "body": "..." } },
  "data": {
    "card": {
      "card_item_id": "4c2b1a09-...",
      "item_header": "Your sleep was restless last night",
      "item_body": { "main": "...", "description": "...", "header": "Sleep recovery" },
      "supported_actions": { "action_keys": ["simplify_plan", "dismiss"] },
      "item_preprocessing": { "simplify_plan": { }, "audio_summary_url": "https://...", "audio_duration": 42.0 },
      "item_created_at": "2026-04-02T14:30:00Z",
      "interaction_status": "pending",
      "trigger_name": "sleep_recovery"
    }
  }
}

Field reference

Downstream responsibilities

Before delivering a notification to the member you must:

• Validate consent: confirm the member has agreed to coaching nudges.
• MLR (Medical, Legal, Regulatory) review: apply your organization's review policy to AI-generated copy.
• Channel execution: honor user channel preferences. If push isn't engaged within 15 minutes, fall back to SMS or in-app per your delivery policy.

Card data structures

CoachNudgeCard: top-level nudge card resource.

ItemBody: message content rendered on the card. main alone on compact cards; header + main + description on expanded views.

SupportedActions: the action buttons. Always exactly 2 keys.

ItemPreprocessing: pre-computed content keyed by action_key. When the user taps an action button, your client renders the corresponding payload directly; no extra API call required. audio_* fields are present on bounce-back and mood triggers.

Update interaction status

After the user views or acts on a card, your client owns the status update:

PATCH /v1/users/{user_id}/cards/{card_item_id}
content-type: application/json

{ "interaction_status": "opened" }

Lifecycle: pending → opened → completed | dismissed. Also valid: pending → dismissed.

Thrive AI Health does not push status updates back; this PATCH is the only channel.