sales-skills/sales-featureos

FeatureOS Platform Help

FeatureOS (formerly Hellonext) — feedback boards + roadmap + changelog + knowledge base. Note the rebrand left legacy names in place: API keys are prefixed hn_, the embed class is HellonextWidget, and posts are the feature_requests resource.

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. What are you trying to do?

   • A) Read/sync feedback posts, votes, comments via the REST API v3 (API-KEY header)
   • B) Build an OAuth app that other workspaces install (scopes, actor modes, token refresh)
   • C) Receive/verify webhooks (post + changelog events) and react to them
   • D) Embed the widget / identify logged-in users with SSO (ssoToken)
   • E) Map post statuses to a roadmap, or wire a changelog
   • F) Pick a plan, or decide FeatureOS vs Canny/Frill/Featurebase

2. API key or OAuth? Scripting your own org → plain API-KEY (hn_…). An integration other orgs connect → OAuth 2.0 app (foapp_/foot_). Front-end embed → HellonextWidget.

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

Step 2 — Route or answer directly

| If the question is about... | Route to... | |---|---| | Voice-of-customer / survey program strategy (NPS/CSAT/CES) across tools | /sales-customer-feedback {question} | | Aggregating unsolicited feedback across reviews/social/support sources | /sales-noisely {question} | | Public review generation strategy | /sales-customer-reviews {question} | | Connecting FeatureOS to a CRM/PM tool generically (iPaaS) | /sales-integration {question} |

When routing, give the exact command, e.g. "This is a strategy question — run: /sales-customer-feedback build a closed-loop feedback program".

Step 3 — FeatureOS platform reference

Read references/platform-guide.md for the full reference — the boards/roadmap/changelog/KB module map (API vs widget vs UI), pricing tiers + the API plan-gate, the post/customer data model, and quick-start recipes (export posts, handle a webhook, embed + SSO).

Read references/featureos-api-reference.md for the integration surface — base https://api.featureos.app/api/v3, API-KEY: hn_… auth (+ per-user Authorization: Bearer <sso_jwt>), page/per_page pagination (default 30, max 100), 100 req/min rate limit, the full errors table + ERROR_CODE_* codes, OAuth 2.0 apps (token formats, /oauth/apps → /oauth/authorize → /oauth/authorize/consent → /oauth/token, scopes, actor modes, role-capping), webhooks (events, postCompleted payload, retry policy), and the HellonextWidget options.

Answer using only the relevant section. Don't dump the full reference.

Step 4 — Actionable guidance

Focus on the user's specific situation:

• Auth + pagination. API-KEY: hn_<key> against api.featureos.app/api/v3; page with ?page=N&per_page=100 (default 30, max 100). Keep the key server-side; full API access is plan-gated (≈Growth tier and up — verify in-account).
• Posts are feature_requests; status.value is the roadmap column. Read/sync feature_requests (and buckets = boards, votes, comments); map status.value (planned/in_progress/completed) to your roadmap.
• Webhooks: 200 or they retry then disable. Subscribe to post/changelog events; respond 200 fast — failures retry at 5m/30m/2h then the webhook is auto-disabled (email sent). Dashboard webhooks aren't HMAC-signed; keep the URL secret. Dedupe on data.id + timestamp (unix seconds).
• OAuth for multi-tenant apps. Register POST /oauth/apps, request minimum scopes, pick actor mode (app bot vs self user, which is role-capped). Access tokens expire in 24h — refresh (rotation: store the newest foot_/foor_ pair).
• Identify widget users with ssoToken or board activity is anonymous. The class is HellonextWidget (legacy), not FeatureOSWidget.
• It's a feedback-board tool, not VoC surveys or aggregation. For NPS/CSAT programs use /sales-customer-feedback; for mining unsolicited reviews/social use /sales-noisely.

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research (2026-06) — API verbatim from developers.featureos.app; pricing from the live site. Confirm in-account.

1. Rebrand leftovers. Hellonext → FeatureOS, but API keys are still prefixed hn_, the embed class is still window.HellonextWidget, and feedback posts are the feature_requests resource. Don't expect "featureos"-named identifiers.
2. Pagination is page/per_page, not cursors. Default 30, max 100. Loop page until a short/empty page.
3. Webhooks auto-disable after 3 failures (retries at 5m/30m/2h) and aren't replayable — always return 200, and reconcile by polling feature_requests. Dashboard webhooks have no HMAC signature (unlike Frill); secure by URL secrecy / IP allowlist.
4. API access is plan-gated and the docs disagree on the tier (live pricing: "complete API access" from ~Growth $120/mo; Help Center: top "Fly High" plan). Treat full API as a higher-paid feature; verify before building.
5. OAuth access tokens expire in 24h. Refresh is a rotation — the old access and refresh token stop working; persist the newest pair or you'll lock yourself out.
6. self-actor OAuth tokens are role-capped per request. If the authorizing user is downgraded/removed, :write/:manage scopes silently drop to read — don't assume a token's permissions are static.
7. No SSO ssoToken → anonymous feedback. Pass a JWT signed with your org SSO key so votes/posts attach to real accounts.
8. Rate limit 100 req/min/key → 429/ERROR_CODE_RATE_LIMITED. Batch with per_page=100 and back off.

Related skills

• /sales-customer-feedback — Voice-of-customer / survey program strategy across tools (FeatureOS is a feedback-board option) — program design, tool selection
• /sales-frill — Frill platform help (the closest like-for-like feedback-board competitor: boards + roadmap + changelog; cursor pagination + HMAC-signed webhooks)
• /sales-noisely — AI feedback aggregation across reviews/social/support (complement: FeatureOS = solicited boards, Noisely = unsolicited mining)
• /sales-customer-reviews — Public review generation strategy
• /sales-integration — Connecting FeatureOS to a CRM/PM tool via API/webhooks/Zapier
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code

Examples

Example 1: Export all feedback posts and their vote counts via the API (developer/automation)

User says: "How do I pull every feature request and its upvotes out of FeatureOS?" Skill does: Shows GET https://api.featureos.app/api/v3/feature_requests with API-KEY: hn_<key>, paging via ?page=N&per_page=100 (default 30, max 100) until a short page, reading each post's status.value, upvotes_count, bucket, and submitter. Notes the 100 req/min limit (back off on 429), keeping the key server-side, and that webhooks (post_created/post_updated) beat polling for ongoing sync. Result: A complete, paginated export of posts + engagement.

Example 2: Build a webhook that won't get disabled

User says: "FeatureOS keeps disabling my webhook — how do I receive post events reliably?" Skill does: Explains the endpoint must use HTTPS, be public, and return 200; on non-200 it retries at 5m/30m/2h then auto-disables (email sent). Recommends responding 200 immediately and processing async, deduping on data.id + created/updated_at (unix seconds), reading type/event (dashboard postCompleted vs OAuth-app post_completed), and reconciling missed events by polling feature_requests. Flags that dashboard webhooks aren't HMAC-signed. Result: A durable webhook intake that stays enabled.

Example 3: FeatureOS vs Frill vs Canny — which feedback board?

User says: "Small SaaS — should I use FeatureOS, Frill, or Canny for a public feedback board + roadmap?" Skill does: Frames the tradeoff — FeatureOS bundles boards + roadmap + changelog + knowledge base + AI copilot (~$60 Starter / ~$120 Growth, API gated to Growth+), Frill is the cheapest (~$25/mo) with cursor pagination + HMAC-signed webhooks, Canny is pricier (~$400/mo) with deeper enterprise features. Recommends by budget/feature-need and routes broader selection: "run: /sales-customer-feedback choose a product-feedback board tool." Result: A price- and feature-grounded board choice.

Troubleshooting

My API key returns 401 / "API key is invalid"

Symptom: Every request fails with 401. Cause: Wrong header, a key without the hn_ prefix, or a plan without API access. Solution: Send the key in the API-KEY header (not Authorization) — -H 'API-KEY: hn_…'; regenerate from Dashboard → Organization Settings → Advanced. Full API access is plan-gated (≈Growth and up) — confirm your tier includes it. Use HTTPS only.

My webhook stopped firing

Symptom: Events arrived, then silence. Cause: Your endpoint returned non-200; after 3 retries (5m/30m/2h) FeatureOS disabled the webhook. Solution: Check your inbox for the disable notice, fix the endpoint to always return 200 quickly, then re-enable under Organization Settings → Webhooks. Backfill the gap by polling feature_requests. Inspect per-delivery logs in the webhook's view.

Widget feedback is all anonymous

Symptom: Board votes/posts aren't tied to your real users. Cause: The HellonextWidget isn't passing an ssoToken. Solution: Generate a JWT from { "email": "...", "name": "..." } signed with your org SSO key and pass it as ssoToken (the old jwtToken is deprecated). For VoC program strategy beyond boards, use /sales-customer-feedback.