Skip to content

Document the pre-chat form #70

Open

Description

@anurag629

The widget now has a configurable pre-chat form that collects details like name and email before the conversation starts. It shipped in @chatcops/widget 0.4.0, but the docs site only mentions it in the request schema on the Server Setup page. The WidgetConfig reference on the Configuration page also leaves out preChatForm, onLeadCaptured and onPreChatSubmit.

Where to look

  • packages/widget/src/widget.ts (PreChatField, PreChatFormConfig, WidgetConfig, handlePreChatSubmit, showChatView)
  • packages/widget/src/dom/prechat-form.ts (field types and validation)
  • packages/widget/dev.html (a working example config)
  • website/src/content/docs/widget/configuration.mdx
  • website/astro.config.mjs (sidebar)

Acceptance criteria

  • New page website/src/content/docs/widget/pre-chat-form.mdx, added to the Widget section of the sidebar
  • Documents enabled, title, subtitle, submitLabel, and each field option: name, type (text, email, select or textarea), label, placeholder, required, options
  • Explains how the form behaves:
    • it only shows when there is no saved conversation and it hasn't been submitted in this browser session
    • required fields and email format are validated
    • a field named name personalizes the welcome message
    • a field named message is sent as the first chat message
    • answers go to the server as userData (up to 50 fields, names up to 100 characters, each value up to 500 characters) with the next chat request, are re-sent if that request fails, and the server adds them to the system prompt for that request
  • Documents onPreChatSubmit and the preChatSubmit event
  • Notes that the form can only be configured from JavaScript (there are no data-* attributes for it)
  • WidgetConfig in configuration.mdx includes preChatForm, onLeadCaptured and onPreChatSubmit
  • pnpm --filter @chatcops/website build succeeds
  • Docs only, no changeset needed

Want to work on this? Comment below and I'll assign it to you. Please take one issue at a time, branch off dev, and open your PR against dev with Closes #<this issue number>. Setup notes (pnpm, build before test) are in CONTRIBUTING.md.

Activity

  1. added
    documentationImprovements or additions to documentation
    widgetAffects @chatcops/widget package
    hacktoberfestGood pick for Hacktoberfest contributors
    on Sep 30, 2026
  2. masyarakatai commented on Oct 16, 2026

    @masyarakatai
    Contributor

    Happy to take this one. I've read the acceptance criteria and the widget sources (prechat-form.ts, widget.ts). Once assigned, I'll branch off dev and open the PR against dev with Closes #70, docs only.

  3. piyusshhjangid commented on Oct 16, 2026

    @piyusshhjangid
    Contributor

    Hi @anurag629, I'm interested in contributing to this documentation issue. I understand another contributor has already expressed interest, so I wanted to check whether this issue is still available before proceeding.

    If it is available, I'll document the pre-chat form configuration, field options, validation and submission behavior, userData handling, onPreChatSubmit, and the preChatSubmit event. I'll also update the WidgetConfig reference and sidebar, then verify the website build.

    I'll follow the repository's contribution guidelines and open a docs-only PR against dev with Closes #70, if you assign it to me.

  4. anurag629 commented on Oct 16, 2026

    @anurag629
    MemberAuthor

    Hey @masyarakatai, go for it, it's yours!

    Heads up: #150 is open and moves the default select placeholder in prechat-form.ts (Select <label>...) into a new selectPlaceholder string. If it lands before your PR, mention that string in the docs. Everything else in the issue still matches dev.

    @piyusshhjangid masyarakatai asked first, so this one is theirs. I assigned you codercops/toolbelt#82 though.

    Let me know if you have any questions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgood first issueGood for newcomershacktoberfestGood pick for Hacktoberfest contributorswidgetAffects @chatcops/widget package

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions