Help Center
Back to Altyaa

Channel states in the cockpit

What the different banners, badges, and page variants mean on the per-channel coach pages — and what to do about each one.

When you open /home/facebook, /home/instagram, /home/tiktok, or /home/google, the cockpit picks one of a small set of page variants based on the live state of your connection. Each variant tells you exactly what (if anything) you need to do to get your coach back to a healthy state.

This article catalogs every state, the badge you'll see in the sidebar, and the operator action for each.

Sidebar badges at a glance

The platform link in the Channels section of the sidebar carries a small badge that mirrors the page's state. Badge precedence is reauth → audit → attention → count → none — if more than one applies, the most-urgent one wins.

BadgeMeaningClick takes you to
↻ (counter-clockwise arrow)The channel needs to reauthenticate — your token expired or was revoked.The Reconnect banner
! (warning)The channel is partially scoped — coach features are limited.The Repair banner
⏳ (hourglass)TikTok is in audit review (SUBMITTED / IN_REVIEW / CHANGES_REQUESTED).The audit-pending notice
3 (number)Coach has 3 active recommendations for you.The recommendations list
(none)Healthy + no pending work.Standard coach surface

Channel page variants

not_connected — never linked

You see the Connect card with provider-branded button. Nothing about your org is stored at the provider yet.

What you'll see:

  • A short value-prop summary (e.g. "Connect your Facebook Page to start coaching your engagement").
  • The scopes the cockpit will request — each with a one-sentence "why".
  • A Connect button that opens the provider's OAuth dialog in a popup.

Operator action: Click Connect, complete the OAuth dialog in the popup, return to the cockpit. The page reloads to the connected variant within a few seconds.

needs_repair — partial scopes

You see the Repair banner at the top of the channel page. Your token works, but you didn't grant all the scopes the cockpit needs, so some coach features are dark.

What you'll see:

  • A short list of the missing scope(s) and what each enables (e.g. "instagram_manage_insights — needed to power your Reels cadence score").
  • A Re-authorize with full scopes button that opens the OAuth dialog again, this time asking for the complete set.

Operator action: Click Re-authorize with full scopes, tick every box in the provider dialog, return to the cockpit. The page reloads to the connected variant within a few seconds.

reauth — token needs refresh

You see the Reconnect banner. The provider invalidated your token — typically because you changed your provider password, or because a 60-day token-refresh window passed without activity.

What you'll see:

  • A short reason ("your Facebook session expired").
  • A Reconnect button. Click → OAuth dialog → return to cockpit.

Operator action: Click Reconnect. Same flow as initial connect; only the token refreshes — your previous content, schedule, and historical metrics stay intact.

expired — long-lived token aged out

You see the Reconnect banner. Equivalent to reauth for the operator — different cause (the token simply aged out instead of being revoked), same fix.

Operator action: Click Reconnect.

revoked — operator disconnected at the provider

You see the Reconnect banner. Someone in your org went to Facebook → Settings → Apps and Websites (or the equivalent IG/TikTok/Google surface) and removed the cockpit's permission.

Operator action: Click Reconnect. Note that all previously-granted scopes are reset — be sure to grant the full set this time so you land in the connected variant, not needs_repair.

revoke_failed — we tried to revoke and couldn't reach the provider

You see the Reconnect banner with a ShieldAlert icon and a "we lost contact" sub-text. The row in our DB still exists; the provider revoke call returned an error or timed out.

Operator action: Click Reconnect — the new connect cycle will overwrite the stale credentials. If the provider page (Facebook → Apps and Websites → Active) still shows the cockpit, manually revoke there too.

audit_pending — TikTok app audit in review (TikTok only)

You see the Audit pending banner at the top of the TikTok channel page. Your account is connected with full scopes, but TikTok still needs to approve our app's access to your account for publishing — typical for first-time TikTok connects.

What you'll see:

  • The current audit state (SUBMITTED, IN_REVIEW, or CHANGES_REQUESTED) and what each means.
  • The estimated review window (typically 5–10 business days).

Operator action: No action needed during SUBMITTED / IN_REVIEW. For CHANGES_REQUESTED, click the link in the banner to view TikTok's feedback and re-submit.

degraded — connected but a provider call is misbehaving

You see the connected variant, but with a small amber banner. Provider responses are intermittently failing (5xx, timeouts, or rate-limit pressure). Reads still work; writes may queue.

Operator action: Usually none — the cockpit's retry logic handles most degradation transparently. If the banner persists for more than 30 minutes, check Slack #altyaa-ops for an incident notice.

ok — healthy + connected

You see the full coach surface: hero score, focus pillars, publish activity, comments, recommendations. This is the default operating state.

Operator action: Use the coach — review recommendations, reply to comments, publish to the queue.

When the cockpit doesn't load at all

Two kill switches can short-circuit the cockpit even when your channels are healthy:

  • ALTYAA_COCKPIT_KILL=1 — an emergency operator switch. When set in our deploy environment, every channel page renders the not_connected variant until the switch is removed. We use this during incidents to avoid surfacing partial state to operators.
  • Per-channel rollout gates — enableCockpitGoogle, enableCockpitFacebook, enableCockpitInstagram, enableCockpitTikTok. If your org isn't yet enrolled for a given channel, that channel renders not_connected regardless of whether you're actually connected. Contact support to be added to the pilot cohort.

For TikTok specifically, there's an additional gate: tiktokAuditDisclosureApproved. Both enableCockpitTikTok and the disclosure gate must be true for the TikTok cockpit to leave not_connected.

Synthetic monitoring

We probe the cockpit every minute via /api/health/cockpit. If you're an operator watching the dashboard:

  • status: "ok" — all channels resolve successfully against the sentinel org.
  • status: "degraded" — one or more channels failed. The response payload names which channel(s) and the reason.
  • status: "disabled" — ALTYAA_COCKPIT_KILL is set.
  • status: "unconfigured" — the sentinel org id env (ALTYAA_COCKPIT_HEALTH_ORG_ID) is unset.

Sentry pages on-call when a channel's resolve throws more than once per five minutes (ISC-DEVOPS-13).

Search documentation

Search through help articles and documentation

  • Features
    • Asset Library
    • Publishing to Google Business Profile
    • Channel states in the cockpit
    • Connecting Facebook Pages
    • Why was my upload rejected?
    • Connecting an Instagram Account