Get Started – Step 2: Connect channels

Route

• Path: /get-started (step 2)
• Parent: stepper.md

Historical design reference

These Figma links are kept for legacy context only. If they differ from the onboarding docs or the shipped overlay, follow the docs and current implementation.

• Figma: Get started – Step 2 (default)
• Figma: Get started – Step 2 (established)

Purpose (business goal)

Connect selected channel types to the workspace so inbound conversations and outbound replies can flow through ConversionIQ.

Architecture: shared connection flows

Step 2 reuses shared connection flow components extracted into src/components/onboarding/shared-connection-flows.tsx. Both the Get Started overlay (step-2.tsx) and the Add Channel wizard (add-channel-wizard.tsx) import from this shared module.

What is shared

Export	Type	Used by
PlatformIcon	Component	Step 2 sections (social, review, messenger, WhatsApp, SMS)
PLATFORM_LOGO	Constant map	Wizard platform picker, channel icon, reviews
SOCIAL_PLATFORMS, REVIEW_PLATFORMS	Constant arrays + types	Wizard family/platform steps, connection button groups
WebChatSnippetBlock	Component	Step 2 Web Chat section, Wizard Web Chat connect step
SmsNumberPicker	Component	Step 2 SMS section, Wizard SMS connect step
CHATTI_WIDGET_SNIPPET	Constant	Snippet code block (used by WebChatSnippetBlock)
FAKE_PHONES_WA, FAKE_PHONES_SMS	Constants	Demo phone labels
DEMO_COUNTRY_CODES, DEMO_SMS_NUMBERS	Constants	SMS number picker options

The wizard re-exports PLATFORM_LOGO, SOCIAL_PLATFORMS, REVIEW_PLATFORMS, and their types from the shared module so existing imports from other files are not broken.

Key differences from the wizard

• No Destination step: Get Started does not show a workspace/KB/agent picker. All connections are auto-assigned to the resolved onboarding target (see README.md §Onboarding target).
• No addedVia field: Connections from Get Started omit addedVia so the overlay session-dismiss behavior works correctly.
• Onboarding target resolution: Before any connection is created, the overlay resolves the onboarding target IDs. If the target workspace/group/KB/agent is missing, they are recreated. See Default Workspace, Knowledge Base & Agent §6.
• Staged-session behavior: Get Started Step 2 does not write live channel connections immediately. It keeps a session-scoped staged connection list that is shown only inside the onboarding overlay until Step 3 is completed.
• Hybrid connect UX: Get Started keeps its per-card instruction copy and always-visible channel sections, but provider-backed connect actions reuse the wizard-style auth flow and per-channel connect controls where practical.

User roles & permissions

• Workspace Admin
• Permission: channels.connect (TBD)

Reference: Roles & Permissions Model

Layout structure

• Fullscreen overlay wrapper (see stepper.md)

• Top-right controls (in overlay header):

  • Chatti Live pill (optional; opens assistant panel)
  • Close icon (dismiss overlay)

• Step header: horizontal 3-step indicator (interactive; see stepper.md)

• Title + subtitle explaining channel connection (“you can add/remove later”)

• Channel connection sections (shown for channel types selected in Step 1; selection propagation rules are in stepper.md).

  All channel sections share the same layout structure:

  1. Icon and title — name of the channel (e.g. Social comments, WhatsApp, SMS).
  2. Instructions title — heading for the steps below.
  3. Instruction step list — ordered list of steps the user should follow.
  4. Channel-specific control set — each channel has its own controls (combobox, buttons, inputs, tabs, etc.).

  Per-channel content:

  • Social comments
    • Instructions text (UI-level)
    • Shared-profile combobox (shown when ≥ 1 Facebook profile exists in another section): multi-select combobox with chips-inside-input and dropdown with checkmarks — see § Shared Facebook profile combobox below
    • Platform buttons: Facebook / Instagram / LinkedIn / Threads
    • Clicking a platform button opens the same simulated provider auth modal pattern used by the Add Channel wizard; the chip is added after successful sign-in
    • Established state: connected profiles rendered as removable chips (e.g., “Facebook profile 1”)
  • Review platform
    • Instructions text (UI-level)
    • Platform buttons: Trustpilot / Google Reviews / Yelp
    • Clicking a platform button opens the same simulated provider auth modal pattern used by the Add Channel wizard; the chip is added after successful sign-in
    • Established state: connected sources rendered as removable chips
  • Facebook Messenger
    • Wizard-style connect tabs:
      • New profile: add-profile action opens the simulated Facebook auth modal and creates a new Messenger profile chip after successful sign-in
      • Select existing one: shows the Get Started-specific Shared-profile combobox (shown when ≥ 1 Facebook profile exists in another section): multi-select combobox with chips-inside-input and dropdown with checkmarks — see § Shared Facebook profile combobox below
    • Established state: connected profiles rendered as removable chips
  • Web Chat
    • Embed snippet code block + “Copy code”
    • Widget title input (TBD)
    • Set appearance opens a dialog window with the same placeholder customization step used by the Add Channel wizard
    • Check status remains a lightweight placeholder action in MVP
  • WhatsApp
    • “Add number” action
    • Clicking Add number opens the same simulated provider auth modal pattern used by the Add Channel wizard; the number chip is added after successful sign-in
    • Established state: connected phone number chips
  • SMS
    • Reuses the same shared SMS number-picker flow as the Add Channel wizard
    • Input fields + instructions for selecting a country code, area code, and available number
    • Established state: connected phone number chips

• Footer actions:

  • Previous
  • Next (enabled when required channel connections are satisfied; gating rules TBD)

Components used

• Workspace Card (context): Component: Workspace Card
• Channel Card: Component: Channel Card (Step 1 selection surface; Step 2 is form/section based)

States

• Empty: no channel types selected in Step 1
  • Show guidance and route the user back to Step 1.
• Default: channel sections shown; no connections established yet (no chips)
• Established: one or more channel connections established; chips shown per section
• Loading: fetch connector status / connection inventory
• Error: auth failed / token expired / missing permissions
• Complete: all required channels connected for Step 3 to proceed (definition of “required” is TBD)

Business logic (high-level)

• Connection flows differ per channel type (OAuth vs token vs webhook).
• Persist connection state and surface degraded/partial scopes.
• MVP interaction (prototype/fake connect behavior):
  • Clicking a provider-backed connect action first opens a simulated auth/login modal.
  • Successful sign-in adds a connected “chip” entry to that section in the staged Step 2 session state.
    • Facebook: add Facebook profile 1, then Facebook profile 2, etc.
    • Instagram: add Instagram profile 1, etc.
    • WhatsApp/SMS: add a chip with a fake phone number (format TBD).
  • Removing a chip is destructive:
    • Clicking chip “X” opens a confirmation modal.
    • Confirm removes the chip; cancel keeps it.
    • This mirrors a real disconnect action that is not easily undoable.
• Session-only scope before completion:
  • Step 2 shows only connections created within the current Get Started session.
  • Existing workspace channels are not rendered in the onboarding Step 2 sections.
  • Staged Step 2 connections survive overlay close / reopen during the same login session.
  • Staged Step 2 connections are cleared on the next login if onboarding is not completed.
• Commit boundary:
  • The staged Step 2 connections are committed into the real workspace Channels state only when the user clicks Complete on Step 3.
  • At commit time, all staged connections are auto-assigned to the onboarding target IDs (workspace, KB, agent). The knowledgeBaseId is set to the onboarding KB for direct-KB channels; agent-managed channels are assigned via the onboarding workspace’s default agent.
• Cross-surface rule:
  • Connections established here must reflect on Account > Channels only after onboarding completion commit.

Domain refs:

• Domain: Channels
• Domain: Workspaces

API dependencies

• GET /workspaces/{id}/channels
• POST /channels/{type}/connect
• POST /channels/{type}/disconnect

Enterprise constraints

• Credential storage and rotation
• Audit on connect/disconnect

Edge cases

• OAuth callback mismatch
• Connector provider outage

Security & compliance considerations

• Never display secrets
• Require re-auth for sensitive changes

Reference: Security & Compliance

Analytics events (if applicable)

• channel.connected
• channel.connection_failed

Reference: Analytics Events (MVP)

---

Shared Facebook profile combobox

Purpose

When a user has already connected one or more Facebook profiles in one channel section (e.g. Social Comments), those same profiles can be reused in another section (e.g. Facebook Messenger) without re-authenticating. The combobox surfaces these already-connected shared profiles as a convenient multi-select picker.

The combobox is only rendered when availableToSelect.length > 0 (i.e. there is at least one shared Facebook profile not yet added to the current section).

Visual design

┌──────────────────────────────────────────────────┐
│  [Facebook profile 1 ×]  [Facebook profile 2 ×]  │  ← chips inside input
│  Filter profiles…                          ▾      │  ← text input + chevron
└──────────────────────────────────────────────────┘
          ↓ (dropdown, opens below)
┌──────────────────────────────────────────────────┐
│  ✓  Facebook profile 1                           │  ← selected (checkmark)
│     Facebook profile 3                           │  ← unselected
│  ✓  Facebook profile 4                           │  ← selected (checkmark)
└──────────────────────────────────────────────────┘

• Trigger / input box: rounded border (rounded-[8px] border border-[#e5e5e5]), white background, min-height h-auto (grows with chips). Contains:
  • Zero or more dismissible chip tags (label + × button), styled consistently with the existing ProfileChip component but smaller (inline, h-6, text-[12px]).
  • A plain <input type="text"> for filtering, placeholder "Filter profiles…".
  • A chevron icon (right side) that toggles the dropdown.
• Dropdown list: appears below the trigger, w-full, white background, rounded-[8px] border border-[#e5e5e5] shadow-md, z-50. Each row:
  • Profile label (text-[14px] text-[#0d0d0d]).
  • Checkmark icon on the right when selected (uses the existing CheckIcon SVG from select.tsx).
  • Hover state: bg-[#f5f5f5].
• Empty filter state: show "No profiles found" in muted text.
• Focus / open state: trigger border becomes border-[#0d0d0d].

Behaviour

Action	Result
Click trigger / input	Opens dropdown
Type in input	Filters list to profiles whose label contains the query (case-insensitive)
Click unselected row	Adds that profile to selected set; chip appears in trigger; row gains checkmark
Click selected row	Removes that profile from selected set; chip disappears; checkmark removed
Click chip ×	Removes that profile from selected set
Click outside	Closes dropdown; clears filter text
Press Escape	Closes dropdown; clears filter text

Multi-select: any number of available profiles can be selected simultaneously.

Connection naming

• Newly created social/review/FB labels use workspace-oriented, human-readable names (brand-like handles/pages) based on workspace and platform (MVP Step 2 uses the default workspace), replacing legacy generic Profile N labels.

Props interface

interface SharedProfileComboboxProps {
  /** All available (unconnected) shared Facebook profiles for this section */
  options: ChannelConnection[];
  /** Currently selected profile labels */
  selectedLabels: string[];
  /** Called when the selected set changes (full new array of labels) */
  onChange: (labels: string[]) => void;
  placeholder?: string; // default: "Filter profiles…"
}

Integration in step-2.tsx

Both FacebookMessengerSection and SocialCommentsSection receive:

• sharedFacebookProfiles: ChannelConnection[] — all shared FB profiles (already passed)
• onAddExisting: (label: string) => void — called once per profile to add (already passed)

The sections compute availableToSelect (profiles not yet in their chip list). The combobox replaces the <select> element. Because the combobox supports multi-select, the onChange callback receives the full new array of selected labels; the section must diff against the previous selection and call onAddExisting for each newly added label.

Note: The existing onAddExisting prop signature ((label: string) => void) is single-add. The section component will loop over newly selected labels and call it once per label, keeping the parent API unchanged.

File location

src/components/onboarding/SharedProfileCombobox.tsx — a self-contained component, no new library required (pure React + Tailwind).