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

# Best Practices

> Tips for deploying an effective chat widget and proactive triggers

## Widget Setup

<AccordionGroup>
  <Accordion title="Write compelling greeting messages">
    Greeting messages appear above the bubble before the user opens the chat. Make them:

    * **Specific**: "Questions about our pricing plans?" beats "Need help?"
    * **Action-oriented**: Tell users what you can help with
    * **Brief**: 1-2 sentences max per greeting card
    * **Varied**: Use 2-3 different greetings to avoid repetition

    Configure greetings in **Branding → Content → Message Greetings**.
  </Accordion>

  <Accordion title="Choose the right auto-open timing">
    Auto-open shows the chat frame automatically after a delay:

    * **Don't auto-open on landing pages** — let users explore first
    * **Auto-open on support/help pages** — users are already looking for help
    * **5-10 seconds** is a good default delay
    * **Disable for mobile** — screen space is limited, let users choose to open
  </Accordion>

  <Accordion title="Use SSO for logged-in users">
    If your site has authentication, use SSO to identify users:

    * Agent can greet them by name
    * Conversation history persists across sessions
    * Support team sees who they're talking to
    * See [SSO setup guide](/saas/chat-widget/sso) for implementation
  </Accordion>

  <Accordion title="Match your brand">
    The widget inherits your agent's branding:

    * **Accent color**: Set in Branding → Design. Use your primary brand color.
    * **Avatar**: Upload a recognizable icon or team photo
    * **Bubble icon**: Choose from 16 icons or use your avatar
    * **Position**: Bottom-right works for most sites. Use bottom-left if you have a conflicting element.
  </Accordion>
</AccordionGroup>

## Trigger Timing

<AccordionGroup>
  <Accordion title="Don't trigger immediately">
    Give users time to orient themselves before offering help.

    **Recommended delays:**

    * Simple pages: 30-45 seconds
    * Complex forms: 45-90 seconds
    * Technical setup: 90-180 seconds
  </Accordion>

  <Accordion title="Detect genuine friction, not exploration">
    Distinguish between:

    * User reading carefully (good)
    * User stuck and frustrated (needs help)

    Use multiple signals: time + inactivity + scroll position.
  </Accordion>

  <Accordion title="Use exit intent carefully">
    Exit intent (mouse leaving window) is powerful but can feel aggressive.
    Reserve for high-value pages like checkout.
  </Accordion>
</AccordionGroup>

## Trigger Frequency

<AccordionGroup>
  <Accordion title="Limit triggers per session">
    * Max 2-3 triggers per session
    * Never more than 1 at a time
    * Wait 5+ minutes between triggers
  </Accordion>

  <Accordion title="Respect dismissals">
    If a user dismisses a trigger:

    * Don't show the same trigger again that session
    * Consider a 24-hour cooldown for that event
    * Track dismissal patterns to improve targeting
  </Accordion>

  <Accordion title="Avoid trigger fatigue">
    Users who see too many triggers become blind to them.
    Quality over quantity - fewer, better-timed triggers perform better.
  </Accordion>
</AccordionGroup>

## Messaging

<AccordionGroup>
  <Accordion title="Be specific, not generic">
    ❌ "Need help?"
    ✅ "Having trouble with payment? I can help!"

    ❌ "Click here for support"
    ✅ "Stuck on this step? I can walk you through it."
  </Accordion>

  <Accordion title="Match your brand voice">
    If your brand is:

    * Professional: "Need assistance with checkout?"
    * Friendly: "Hey! Can I help with that?"
    * Technical: "Encountering an issue? Let's debug together."
  </Accordion>

  <Accordion title="Create urgency without pressure">
    ✅ "Your cart is saved for 30 minutes"
    ❌ "Buy now or lose your cart!"

    ✅ "Questions before you go?"
    ❌ "Don't leave! We need you!"
  </Accordion>
</AccordionGroup>

## Context

<AccordionGroup>
  <Accordion title="Pass relevant data with triggers">
    The more context your agent has, the better it can help:

    ```javascript theme={null}
    // Good
    boostgpt.trigger('checkout_help', {
      cart_value: '$149',
      items: 3,
      user_name: 'Sarah',
      time_on_page: 45,
      current_step: 'payment'
    });

    // Not as helpful
    boostgpt.trigger('help', {});
    ```
  </Accordion>

  <Accordion title="Include user info when available">
    ```javascript theme={null}
    boostgpt.trigger('help_needed', { page: '/settings' }, {
      text: 'Need help with settings?',
      user: {
        id: 'user_123',
        name: 'Sarah Chen',
        email: 'sarah@example.com',
        plan: 'pro'
      }
    });
    ```

    This enables personalized responses.
  </Accordion>

  <Accordion title="Capture the user's journey">
    Include:

    * Current page/step
    * Previous pages visited
    * Actions already taken
    * Time spent
  </Accordion>
</AccordionGroup>

## Trigger Style

<AccordionGroup>
  <Accordion title="Trigger cards stack above the widget bubble">
    Triggers appear as toast-style message cards stacked above the chat widget bubble.
    They feel personal and conversational — clicking opens the chat with context.
  </Accordion>

  <Accordion title="Use text to match the situation">
    | Situation         | Example Text                                      |
    | ----------------- | ------------------------------------------------- |
    | Checkout help     | "Having trouble checking out? I can help!"        |
    | Onboarding stuck  | "Stuck on this step? Let me walk you through it." |
    | Error recovery    | "Something went wrong. Click here for help."      |
    | Feature discovery | "Did you know you can automate this?"             |
  </Accordion>
</AccordionGroup>

## Training Your Agent

<AccordionGroup>
  <Accordion title="Include relevant knowledge">
    Your agent should know:

    * Product features and pricing
    * Common issues and solutions
    * Policies (shipping, returns, refunds)
    * Technical documentation
  </Accordion>

  <Accordion title="Write good prompt templates">
    Templates should:

    * Describe the situation clearly
    * Include all relevant context
    * Provide instructions on how to help
    * Set the right tone
  </Accordion>

  <Accordion title="Test with real scenarios">
    Before deploying, test:

    * Common user questions
    * Edge cases
    * Error scenarios
    * Various context combinations
  </Accordion>
</AccordionGroup>

## Analytics & Optimization

<AccordionGroup>
  <Accordion title="Track key metrics">
    | Metric             | What It Tells You                    |
    | ------------------ | ------------------------------------ |
    | Widget Opens       | How often users engage with the chat |
    | Trigger View Rate  | How often users see trigger cards    |
    | Trigger Click Rate | How often users click trigger cards  |
    | Resolution Rate    | How often chat resolves the issue    |
    | Conversion Lift    | Impact on desired outcomes           |
  </Accordion>

  <Accordion title="A/B test variations">
    Test variations of:

    * Trigger message text
    * Trigger timing and delay
    * Greeting messages
    * Auto-open vs manual open
  </Accordion>

  <Accordion title="Iterate based on data">
    * High view, low click: Message isn't compelling
    * High click, low resolution: Agent needs better training
    * Low view: Trigger timing/conditions need adjustment
  </Accordion>
</AccordionGroup>

## Common Mistakes

<Warning>
  **Don't do these:**
</Warning>

1. **Triggering on page load** - Let users settle first
2. **Too many triggers** - Causes fatigue and annoyance
3. **Generic messages** - "Need help?" is forgettable
4. **Blocking the page** - Never prevent users from continuing
5. **No dismiss option** - Always let users close triggers
6. **Same trigger repeatedly** - Respect when users say no
7. **Ignoring mobile** - Test on all devices
8. **No analytics** - You can't improve what you don't measure

## Checklist

Before launching, verify:

**Widget:**

* [ ] Accent color matches your brand
* [ ] Greeting messages are specific and helpful
* [ ] Auto-open timing is appropriate (or disabled)
* [ ] SSO configured for authenticated users
* [ ] Works on mobile devices
* [ ] Position doesn't conflict with other page elements

**Triggers:**

* [ ] Timing feels natural, not aggressive
* [ ] Trigger messages are specific and helpful
* [ ] Agent is trained on relevant content
* [ ] Dismissals are respected
* [ ] Rate limits won't be exceeded
* [ ] Legal/privacy requirements are met

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/saas/quickstart">
    Set up your first widget and trigger
  </Card>

  <Card title="Use Case Guides" icon="book" href="/saas/guides/checkout-abandonment">
    Real-world implementations
  </Card>
</CardGroup>