Skip to content
⌘K
InboxAsk a human

Step 8: Developing your self-serve strategy

Updated by Dustin

The final step in setting up your workspace at scale is giving customers a place to find answers on their own and giving enterprise accounts organization-wide visibility into their conversations. For a scaling or multi-product organization, self-serve comes down to two things: separating documentation across products, brands, and internal/external audiences so AI answers never cross-contaminate, and giving enterprise customers a shared ticket portal. This can either be done through Plain's hosted Customer Inbox (with explicit Account sharing and structured intake forms) or through a white-label headless support portal embedded directly inside your product via Plain's GraphQL API.

You can set up multiple Help Centers and multiple Customer Inboxes, plus programmatic access to the Help Center and thread APIs so your docs and product teams can run docs-as-code in CI and embed support natively in your app. This page walks through structuring multiple Help Centers, wiring an idempotent CI docs sync, and standing up either the hosted Customer Inbox or a headless portal.

What good looks like

You’ll want to see a clean separation between public, gated, and internal knowledge bases, paired with a self-serve portal where an enterprise admin can see every ticket their organization has open across Slack Connect, email, and in-app forms:

  • Audience-isolated Help Centers: Public product docs, gated enterprise/beta docs, and internal T1/T2 runbooks live in separate Help Centers with explicit Access controls (Everyone, Authenticated customers scoped by Tier/Account, or Your team with Plain AI set to Allow)

  • CI / docs-as-code pipeline: Articles are migrated or mirrored continuously from Git/MDX on merge to main via upsertHelpCenterArticle and helpCenterArticleBySlug

  • Organization-wide ticket portal: Customers can view and reply to all threads belonging to their explicit Account (and submit structured new requests that populate Thread fields) — either via the hosted Customer Inbox today or via an embedded headless portal in your product dashboard

Three architectural choices to make upfront

1. One Help Center with nested groups vs. multiple Help Centers

You can run multiple Help Centers, so you don't have to cram multiple products or internal runbooks into one site. Use this rule of thumb to decide when to split:

Scenario

Recommended structure

Access & AI configuration

One product with several modules

Single Help Center with nested article groups (parentHelpCenterArticleGroupId)

Access: Everyone (publicly indexed by search engines, Ask AI, and the Customer Agent)

Distinct products or brands (Compute vs. Data, or an acquired brand)

Separate Help Center per product/brand (help.compute.example, help.data.example)

Access: Everyone on each custom domain; prevents Ask AI on Product A's site from citing Product B's articles

Gated enterprise, partner, or beta documentation

Dedicated gated Help Center

Access: Authenticated customers, scoped by Tier, Account, or Customer (rules are OR'd together)

Internal T1/T2/T3 engineering runbooks & SOPs

Dedicated internal Help Center

Access: Your team (invisible to customers) with Plain AI set to Allow so Sidekick and the Customer Agent can use the runbooks without exposing internal URLs

2. Hosted Customer Inbox vs. building a headless support portal

You don't have to block your Plain launch waiting on frontend engineering to build a custom in-app ticket portal — many scaling teams turn on the hosted Customer Inbox on day one and transition to (or run alongside) a headless portal later:

  • When to use the hosted Customer Inbox ("Your requests"): You want a zero-engineering portal where enterprise teammates can log in (via a 6-digit email code or WorkOS SSO/AuthKit on gated Help Centers), see every thread opened by anyone in their explicit Account across Slack Connect, email, and chat, and submit new requests through Custom forms that map directly to your Thread fields.

  • When to build a headless support portal on the GraphQL API: You want the ticket table, custom status badges, SLA indicators, and composer embedded natively inside your product's logged-in console (app.yourproduct.com/support) using your own auth session and design system. Plain acts as the headless backend; your server queries Plain's GraphQL API scoped to the logged-in user's accountId / externalId.

3. Authoring in Plain's UI vs. continuous CI mirroring from Git

If your technical writers or engineers already maintain docs in MDX/Markdown in GitHub (Mintlify, Docusaurus, Nextra, etc.), keep them there. Plain's Help Center GraphQL API (createHelpCenterArticleGroup, helpCenterArticleBySlug, upsertHelpCenterArticle, updateHelpCenterIndex) lets a lightweight GitHub Action mirror articles into Plain on every merge to main so you get Plain's hosted Ask AI, Customer Inbox, and automatic Customer Agent indexing without changing how your team writes docs.

Implementation blueprint

For the basics of creating a Help Center and migrating your docs into it, see Step 8: Setting up your Help Center and Customer Inbox in our small-team series.

1. Stand up your Help Centers, access controls, and custom domains

  1. Under Help Center, create your Help Center shells (e.g. Public Docs, Internal Runbooks)

  2. In Help Center → Access, set Access (Everyone, Authenticated customers with Tier/Account rules, or Your team with Plain AI set to Allow)

    Make a Help Center internal-only
  3. In Help Center → Domains, claim the immediate *.support.site subdomain so you can test right away, and hand the custom domain CNAME (help.yourcompany.com) to your DNS admin (SSL provisions automatically once DNS propagates)

2. Wire your CI docs mirror (or run an agentic migration from Zendesk/Intercom)

Never copy-paste hundreds of articles by hand. Create a machine user under Settings → Machine users & Agents with helpCenter:edit, helpCenter:read, helpCenterArticle:read, and helpCenterArticleGroup:read, and either run a one-time migration via Cursor / Claude Code or drop a sync step into your Git CI pipeline.

How an idempotent CI sync works:

  1. Resolve or create article groups: Query or create your category hierarchy with createHelpCenterArticleGroup (pass parentHelpCenterArticleGroupId for nested subcategories).

  2. Look up existing articles by slug first: Before upserting, query helpCenterArticleBySlug (helpCenterId + slug).

    • If it returns an existing article, pass its id as helpCenterArticleId in upsertHelpCenterArticle to update it in place.

    • If it returns null, omit helpCenterArticleId to create it (calling upsertHelpCenterArticle without helpCenterArticleId on an existing slug will fail with a duplicate-slug error).

  3. Pass clean HTML and status: PUBLISHED: Convert Markdown/MDX to clean HTML (re-hosting any images that currently live on private Zendesk/Intercom URLs onto a public CDN first) and explicitly set status: PUBLISHED (upsertHelpCenterArticle requires status and rejects the call if it is omitted, and DRAFT articles are hidden from customers, Ask AI, and the Customer Agent).

  4. Lock in sidebar ordering (optional): Query helpCenterIndex for the current hash and pass your ordered navigation tree to updateHelpCenterIndex.

query ($helpCenterId: ID!, $slug: String!) { helpCenterArticleBySlug(helpCenterId: $helpCenterId, slug: $slug) { id slug } } mutation { upsertHelpCenterArticle(input: { helpCenterId: "hc_01J..." helpCenterArticleGroupId: "hcag_01J..." helpCenterArticleId: "hca_01J..." # pass existing id from helpCenterArticleBySlug, or omit on first create title: "Configuring VPC peering on Compute" slug: "configuring-vpc-peering" description: "Set up private networking between your VPC and Compute clusters." contentHtml: "<p>Head to <strong>Networking → VPC Peering</strong> to create a connection.</p>" status: PUBLISHED }) { helpCenterArticle { id slug status } error { message } } }

3A. Configure the hosted Customer Inbox for enterprise Account visibility

(Prerequisite: The Email channel must be enabled so Plain can send login verification codes.)

  1. Open Help Center → Customer Inbox and toggle on Customer Inbox

  2. Under Default thread visibility, check Threads from anyone with the same account — this lets every member of an explicit Account view and reply to their organization's threads across Slack Connect, email, and portal forms.

    • Important: Threads from anyone with the same account strictly evaluates explicit Accounts (CRM-synced, API-upserted, or Slack-linked) and intentionally ignores automatic domain-based accounts so shared domains never leak tickets. You can also give specific Accounts or customers extra visibility under Thread visibility overrides on the same page.

Share one account's threads with extra visibility
  1. Under Custom forms, build structured intake forms mapped to your Thread fields . On a dropdown, open an option, choose Add action, then Thread fields. Portal submissions then arrive pre-tagged for your workflows.

    Add a field to the Customer Inbox custom form

3B. Architecture of a headless support portal (embedded in your app)

If you're building a white-label support portal inside your product dashboard, keep the Plain machine user API key strictly on your backend and expose a thin authenticated relay to your frontend:

  1. Authenticate & scope on your backend: Read the logged-in user's identity and active organization/workspace from your own session token, mapping them to Plain's customerIdentifier (externalId) and accountIdentifier (externalId).

  2. Query the organization's thread list (threads): Call threads(filters: { accountIdentifiers: [{ accountId: "te_01J..." }] }) (or filter by customerIds for a "My tickets" tab) to render the ticket table with statuses, priorities, custom thread fields, and timestamps. (Map Plain's internal statuses to customer-friendly labels just like the Customer Inbox does: Todo / Snoozed → In progress, Waiting for customer → Waiting for you, Done → Done.)

  3. Render the conversation timeline & attachments (thread): Fetch the thread's timeline entries, and use createAttachmentDownloadUrl and createAttachmentUploadUrl to generate short-lived signed URLs for file downloads and uploads.

  4. Submit new tickets & replies (createThread / replyToThread): Call createThread passing customerIdentifier, accountIdentifier, and threadFields for new requests, and post follow-ups like this. On a Chat thread, the customer posts with sendCustomerChat (customerId, threadId, and text). On other threads (email, Customer Inbox, Slack), call replyToThread with impersonation.asCustomer, which needs the customer:impersonate permission and a machine user. Teams and Discord threads don't support it, and an email thread needs a real customer address. A reply from your team is replyToThread without impersonation.

Routing reminder for both portal paths: Threads from the hosted Customer Inbox's New request form arrive on the Email support channel. Threads from your headless portal's createThread mutation arrive on the API support channel unless you pass a different channel. If you build a headless portal, make sure your routing and SLA workflows include API in any channel filters (not just Email and Slack).

Verification checklist

  1. Audience & AI isolation check: Open your public Help Center in an incognito window and ask Ask AI a question covered in your public docs and one covered only in your internal Your team runbook Help Center. Confirm Ask AI cites the public article and never exposes internal-only runbook links to customers (while Sidekick inside a Plain thread can read the internal runbook).

  2. Cross-colleague Account visibility: Log into the Customer Inbox (or your headless portal) as two different users attached to the same explicit Account in Plain, and verify User B can see and reply to a thread that User A opened in Slack Connect or email.

  3. Structured portal intake → routing: Submit a New request with custom form fields (product_area = Compute, severity = P1) and confirm the thread arrives on the Email channel (hosted Customer Inbox) or the API channel (headless portal) with its Account, Tier, and Thread fields populated and routes to the right regional team.

Troubleshooting/FAQ

Colleagues at the same enterprise customer can't see each other's threads in the Customer Inbox.

Organization-wide visibility in the Customer Inbox is opt-in and requires both users to belong to the same explicit Account in Plain. Check these three causes:

"Threads from anyone with the same account" is unchecked

  • By default, a customer only sees threads they opened themselves.

  • Try this: Open Help Center → Customer Inbox and enable Threads from anyone with the same account under Default thread visibility (or add the Account under Thread visibility overrides on the same page to share just that Account's threads).

The thread has no Account

  • Colleagues only see each other's threads through the Account the thread carries, so a thread with no Account isn't shared.

  • Try this: Check that the thread has the customer's Account attached.

The users are only grouped by a domain-based account, not an explicit Account

  • To prevent accidental data leaks on shared domains, Threads from anyone with the same account ignores automatic domain-based accounts and only shares threads across explicit Accounts (created via CRM sync, upsertAccount, or a linked Slack channel).

  • Try this: Ensure the customer organization is synced as an explicit Account and both users are linked to it via addCustomerToAccounts or your CRM sync.

Our CI sync script failed with a duplicate slug error (or articles are in Plain but invisible on the Help Center and Ask AI).

Two details in upsertHelpCenterArticle trip up automated sync scripts:

The script didn't pass helpCenterArticleId when updating an existing article

  • Omitting helpCenterArticleId tells Plain to create a brand-new article, which fails if an article with that slug already exists in that Help Center.

  • Try this: Query helpCenterArticleBySlug first using helpCenterId and slug. If an article exists, pass its id as helpCenterArticleId in upsertHelpCenterArticle; if null, omit helpCenterArticleId.

status was omitted or set to DRAFT

  • upsertHelpCenterArticle requires status and rejects calls that omit it, and Draft articles are hidden from customers, Ask AI, and the Customer Agent.

  • Try this: Pass status: PUBLISHED explicitly in your sync payload once articles are ready to go live (and if the Help Center's access is set to Your team, confirm Plain AI is set to Allow under Help Center → Access).

Threads submitted through the Customer Inbox (or our headless portal) aren't triggering our routing or SLA workflows.

Headless portal createThread calls arrive with Support channel set to API (Customer Inbox requests arrive on Email), so any Step 6 workflow filtered strictly to Support channel equals Email or Slack will ignore them.

Try this: Open your routing and SLA workflows on the Workflows page, add API to your channel conditions (or route based on the Thread fields populated by your custom intake form), and republish.

The Customer Inbox toggle is disabled and won't turn on.

The hosted Customer Inbox authenticates users by emailing them a 6-digit verification code, so it can't be enabled until Email is configured as a channel in your workspace.

Try this: Complete your primary email setup under Settings → Channels → Email, then return to Help Center → Customer Inbox.