Nudge library

How library nudges work

1. Tenant library — migrations upsert nudges with source: "library" and a unique libraryKey. IDs are deterministic per tenant.
2. Organization catalog — each org activates a subset via PATCH /v1/organizations/{id} with a nudges array. Members only receive nudges that are active in their org catalog.
3. Member toggles — per-member on/off and schedule overrides use GET/PATCH …/members/…/nudge-settings (see REST API).
4. Reply tracking — set responseType on a nudge and fetch standardized replies via GET /v1/nudges/{key}/replies (see Nudge replies).

HeadRight preset mapping

Map each HeadRight habit preset to the libraryKey below. Resolve the BoomTower nudge id once via GET /v1/nudges (filter source === "library") and cache libraryKey → id.

Integration flow

Recommended approach for HeadRight (server-side, using your organization API key):

1. On connect (or first dashboard load), call GET https://api.boomtower.com/v1/nudges with X-API-Key.
2. Build a map of library nudges: libraryKey → id where source === "library".
3. When a user toggles a preset, PATCH member nudge settings with the resolved nudgeId and enabled.

GET https://api.boomtower.com/v1/nudges
X-API-Key: YOUR_ORG_API_KEY

// Response entries include:
// { "id": "…", "source": "library", "libraryKey": "water", "name": "Drink water", … }

PATCH https://api.boomtower.com/v1/organizations/{orgKsuid}/members/nudge-settings?externalApp=headright&externalId={userId}
X-API-Key: YOUR_ORG_API_KEY
Content-Type: application/json

{
  "data": {
    "overrides": [
      { "nudgeId": "RESOLVED_NUDGE_KSUID", "enabled": true }
    ]
  }
}

Full catalog

Default prompts and schedules below. Times are interpreted in each member's timezone when nudges are sent.

Example preset map (TypeScript)

// presets.ts — stable mapping; resolve ids at runtime from GET /v1/nudges
export const PRESET_LIBRARY_KEYS = {
  water: 'water',
  pushups: 'pushups',
  stretch: 'stretch',
  walk: 'walk',
  breath: 'breath',
  posture: 'posture',
  gratitude: 'gratitude',
  sleep: 'sleep',
} as const;

export async function resolveLibraryNudgeIds(apiKey: string): Promise<Record<string, string>> {
  const res = await fetch('https://api.boomtower.com/v1/nudges', {
    headers: { 'X-API-Key': apiKey },
  });
  const body = await res.json();
  const map: Record<string, string> = {};
  for (const nudge of body.data ?? []) {
    if (nudge.source === 'library' && nudge.libraryKey) {
      map[nudge.libraryKey] = nudge.id;
    }
  }
  return map;
}