> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> Collect structured data from visitors through AI-powered forms

Forms let your AI chatbot collect structured data from visitors—like feedback, contact details, or survey responses—directly inside the chat. Instead of redirecting visitors to external pages, the chatbot presents a form when it detects the right intent.

## How It Works

1. You **create a form** with the fields you need
2. You give the AI **instructions** on when to show it
3. When a visitor asks something relevant, the AI **presents the form** in the chat
4. The visitor **fills it out and submits**—you get the data instantly

<Note>
  The AI decides when to show a form based on your instructions. Write clear, specific instructions so the AI triggers the form at the right moment.
</Note>

***

## Creating a Form

<Steps>
  <Step title="Navigate to Forms">
    Go to **Dashboard** → select your website → **Forms** in the sidebar
  </Step>

  <Step title="Click Create Form">
    Click the **Create Form** button to open the form builder.
  </Step>

  <Step title="Fill in Form Details">
    * **Name** (required): A clear name like "Product Review Form" or "Contact Request"
    * **Description**: Brief text shown to visitors above the form
    * **AI Instructions**: Tell the chatbot *when* to show this form (e.g., "Show when a visitor wants to leave a product review or feedback")
  </Step>

  <Step title="Add Fields">
    Click **Add Field** and configure each field's type, label, placeholder, and whether it's required. See [Field Types](#field-types) below for all options.
  </Step>

  <Step title="Preview and Save">
    The live preview on the right shows how your form will look to visitors. Click **Create Form** when you're done.
  </Step>
</Steps>

<Tip>
  Write specific AI instructions. "Show when visitor asks about pricing or quotes" works better than "Show when needed."
</Tip>

***

## Field Types

Forms support 8 field types to cover most data collection needs:

| Type                   | Description                       | Use For                   |
| ---------------------- | --------------------------------- | ------------------------- |
| **Text**               | Single-line text input            | Names, short answers      |
| **Email**              | Email input with validation       | Email addresses           |
| **Number**             | Numeric input                     | Quantities, ages          |
| **Long Text**          | Multi-line text area              | Feedback, descriptions    |
| **Dropdown**           | Select one from a list            | Categories, departments   |
| **Radio Buttons**      | Choose one option                 | Yes/No, ratings, choices  |
| **Checkbox**           | Single toggle (checked/unchecked) | Agreements, confirmations |
| **Rating (1-5 Stars)** | Star rating selector              | Satisfaction scores       |

### Field Configuration

Each field has:

* **Label** (required): The question or prompt shown to visitors
* **Type**: The input type from the list above
* **Placeholder**: Hint text inside the field (not available for Checkbox and Rating)
* **Required**: Whether the visitor must fill in this field before submitting

For **Dropdown** and **Radio Buttons**, you also configure a list of options that the visitor can choose from.

### Reordering Fields

Use the up/down arrows on each field to change the order. Fields appear to visitors in the order you set.

***

## AI Instructions

AI Instructions tell your chatbot when to display a form. This is the most important part of form configuration—if the instructions are unclear, the AI won't know when to act.

### Writing Good Instructions

<Tabs>
  <Tab title="Good Examples">
    * "Show when a visitor wants to leave a product review or feedback about their purchase"
    * "Show when a visitor asks for a quote, pricing information, or wants to discuss custom plans"
    * "Show when a visitor expresses interest in becoming a partner or reseller"
    * "Show when a visitor wants to schedule a demo or consultation call"
  </Tab>

  <Tab title="Bad Examples">
    * "Show when needed" (too vague)
    * "Show form" (no context)
    * "When customer" (incomplete)
  </Tab>
</Tabs>

<Note>
  You can create multiple forms per website, each with different AI instructions. The AI will pick the right one based on the visitor's message.
</Note>

***

## Enabling and Disabling Forms

Forms are **enabled by default** when created. You can toggle a form on or off from the Forms list page without deleting it.

* **On**: The AI can see and show this form to visitors
* **Off**: The form is hidden from the AI—visitors won't see it

***

## Viewing Submissions

Every form submission is stored and accessible from your dashboard.

### View Submissions for a Form

Each form in the Forms list has a **submissions count** badge. Click the form's menu to view its submissions. Each submission shows:

* All field values with their labels
* Formatted values (e.g., "4/5 stars" for ratings)
* Submission date and time
* Visitor ID and conversation ID

### Email Notifications

By default, you receive an email notification when a visitor submits a form. The email includes:

* Form name
* Website name
* All submitted field values
* A link to view the submission in your dashboard

***

## Sample Use Cases

### Product Reviews

Collect customer feedback with ratings and detailed reviews.

<CardGroup cols={2}>
  <Card title="Form Details" icon="file-text">
    **Name**: Product Review<br />
    **AI Instructions**: "Show when a visitor wants to leave a review, feedback, or rate a product"
  </Card>

  <Card title="Fields" icon="list">
    1. Text — "Product Name" (required)<br />
    2. Rating — "Overall Rating" (required)<br />
    3. Long Text — "Your Review" (required)<br />
    4. Text — "Reviewer Name"
  </Card>
</CardGroup>

***

### Quote Requests

Capture lead information when visitors ask about pricing.

<CardGroup cols={2}>
  <Card title="Form Details" icon="file-text">
    **Name**: Request a Quote<br />
    **AI Instructions**: "Show when a visitor asks about pricing, quotes, custom plans, or wants to discuss business terms"
  </Card>

  <Card title="Fields" icon="list">
    1. Text — "Full Name" (required)<br />
    2. Email — "Email Address" (required)<br />
    3. Text — "Company Name"<br />
    4. Dropdown — "Interest" (required): Sales, Support, Partnership, Other<br />
    5. Long Text — "Tell us about your needs" (required)
  </Card>
</CardGroup>

***

### Customer Support Tickets

Collect issue details before escalating to your support team.

<CardGroup cols={2}>
  <Card title="Form Details" icon="file-text">
    **Name**: Support Ticket<br />
    **AI Instructions**: "Show when a visitor has a technical problem, wants to report a bug, or needs help that requires follow-up"
  </Card>

  <Card title="Fields" icon="list">
    1. Text — "Full Name" (required)<br />
    2. Email — "Email Address" (required)<br />
    3. Dropdown — "Issue Type" (required): Billing, Technical, Account, Other<br />
    4. Text — "Order/Reference Number"<br />
    5. Long Text — "Describe the issue" (required)
  </Card>
</CardGroup>

***

### Event Registration

Sign visitors up for webinars or events.

<CardGroup cols={2}>
  <Card title="Form Details" icon="file-text">
    **Name**: Event Registration<br />
    **AI Instructions**: "Show when a visitor wants to register for an event, webinar, workshop, or demo"
  </Card>

  <Card title="Fields" icon="list">
    1. Text — "Full Name" (required)<br />
    2. Email — "Email Address" (required)<br />
    3. Text — "Company"<br />
    4. Number — "Number of Attendees"<br />
    5. Dropdown — "Session" (required): Morning, Afternoon, Evening
  </Card>
</CardGroup>

***

### Newsletter Signup

Collect email subscriptions directly in chat.

<CardGroup cols={2}>
  <Card title="Form Details" icon="file-text">
    **Name**: Newsletter Signup<br />
    **AI Instructions**: "Show when a visitor wants to subscribe to the newsletter, get updates, or stay informed"
  </Card>

  <Card title="Fields" icon="list">
    1. Text — "First Name" (required)<br />
    2. Email — "Email Address" (required)<br />
    3. Checkbox — "I agree to receive marketing emails" (required)
  </Card>
</CardGroup>

***

## Editing and Deleting Forms

### Edit a Form

Click the pencil icon on any form to modify its name, description, AI instructions, or fields. Changes take effect immediately.

### Delete a Form

Click the trash icon and confirm. **Deleting a form permanently removes all its submissions**. This action cannot be undone.

<Warning>
  Deleting a form also deletes all submissions for that form. Consider exporting important data before deleting.
</Warning>

***

## How Visitors Experience Forms

When a visitor interacts with your chatbot and the AI decides a form is relevant:

1. The AI sends a brief message (e.g., "I'd love to get your feedback! Please fill out this quick form:")
2. The form appears inline in the chat with all configured fields
3. The visitor fills in the fields and clicks **Submit**
4. Required fields are validated before submission
5. A success message confirms the submission
6. The conversation continues normally

Visitors never leave the chat—the entire experience happens inside the widget.

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Forms Short" icon="minimize-2">
    3-5 fields is ideal. Long forms reduce completion rates.
  </Card>

  <Card title="Specific AI Instructions" icon="message">
    Describe exactly when to show the form. Vague instructions lead to missed triggers.
  </Card>

  <Card title="Mark Key Fields Required" icon="asterisk">
    Only mark fields as required if you truly need the data. Optional fields increase completion rates.
  </Card>

  <Card title="Test Before Going Live" icon="flask">
    Use the preview in the form builder and test via the chatbot to verify the experience.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Form not showing when expected">
    * Check the form is **enabled** (toggle is On)
    * Review your **AI Instructions**—make them more specific
    * Try phrasing your test message differently to match the instructions
    * Ensure the form has at least one field
  </Accordion>

  <Accordion title="Wrong form showing">
    * Check if multiple forms have overlapping AI instructions
    * Make each form's instructions distinct and specific to its purpose
  </Accordion>

  <Accordion title="Submission not received">
    * Check the **Submissions** page in your dashboard
    * Verify the form is enabled
    * Check your email notifications settings
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Custom Tools" icon="wrench" href="/user-guide/integrations/custom-tools">
    Connect your chatbot to external APIs
  </Card>

  <Card title="Human Handoff" icon="headset" href="/user-guide/human-handoff">
    Escalate to live agents
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/user-guide/best-practices">
    Optimize your chatbot setup
  </Card>
</CardGroup>