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

# Playbook: Create a chatbot from a website

> An end-to-end agent playbook for researching a website, creating a SiteGPT chatbot, adding knowledge, and configuring appearance and behavior.

This playbook is written for AI agents and automation scripts. The goal is:

> Given a website URL, create a useful SiteGPT chatbot end-to-end with knowledge, branding, icons, persona, instructions, starters, followups, and initial verification.

Use this page to choose the right setup path. For the full step-by-step flow, use the path-specific playbook:

<CardGroup cols={2}>
  <Card title="New customer onboarding" icon="wand-magic-sparkles" href="/cli/playbooks/agent-first-onboarding-chatbot">
    Build a temporary preview chatbot before signup, then share the onboarding
    URL for preview and claim.
  </Card>

  <Card title="Existing account setup" icon="user-gear" href="/cli/playbooks/account-chatbot-setup">
    Create or update a chatbot inside an authenticated SiteGPT account.
  </Card>
</CardGroup>

## Choose the setup path

Use the right path before running authentication checks:

| Situation                                                                  | Path                                                                            |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| The user does not have a SiteGPT account yet or wants to try SiteGPT first | [Agent-first onboarding chatbot](/cli/playbooks/agent-first-onboarding-chatbot) |
| The user already has a SiteGPT account, token, or saved profile            | [Existing account chatbot setup](/cli/playbooks/account-chatbot-setup)          |

For agent-first onboarding, start with `sitegpt onboarding start`. It creates a temporary chatbot and returns a temporary token. Use that token for the rest of the setup, then share the onboarding URL after the chatbot is useful. `PROFILE_NOT_CONFIGURED` is expected in this flow and should not stop setup.

For existing accounts, log in first and create the chatbot directly in the account.

## Configuration differences

Both flows should produce a well-configured chatbot, but the safety posture is different:

| Area               | Agent-first onboarding                                                            | Existing account                                                                                              |
| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Knowledge          | Add the best initial source and use `onboarding status` checklist before sharing. | List existing docs/jobs before updating; avoid deletes or bulk resync unless asked.                           |
| Brand settings     | Make the preview feel branded immediately before sharing the onboarding URL.      | Read current appearance first; preserve existing choices unless creating a new bot or user asked for refresh. |
| Persona            | Create one strong default and activate it.                                        | List existing personas before replacing active behavior.                                                      |
| Instructions       | Create one active grounded instruction set.                                       | List current instructions and avoid clobbering production behavior without approval.                          |
| Starters/followups | Add broad visitor prompts so the preview is easy to test.                         | Add/refine prompts; do not remove existing prompts without approval.                                          |
| Lead/support       | Enable only when purpose and visible contact details justify it.                  | Respect existing notification/routing settings.                                                               |
| Handoff            | Share onboarding URL and claim path.                                              | Share dashboard/install links and summarize changes.                                                          |

## Required access for existing accounts

Use a profile with these scopes:

```bash theme={null}
sitegpt login \
  --profile setup-agent \
  --scope account:read \
  --scope chatbots:read \
  --scope chatbots:write \
  --scope knowledge:read \
  --scope knowledge:write \
  --scope settings:read \
  --scope settings:write \
  --scope personas:read \
  --scope personas:write \
  --scope instructions:read \
  --scope instructions:write \
  --scope starters:read \
  --scope starters:write \
  --scope followups:read \
  --scope followups:write
```

If you also need to delete mistakes during setup, include the matching delete scopes.

For agent-first onboarding, no login is needed before the first command. The temporary token returned by `sitegpt onboarding start` is scoped to the new chatbot.

## Inputs

Ask for or infer the chatbot purpose before creating the chatbot. If the user did not say, ask one concise question:

```text theme={null}
What should this SiteGPT chatbot optimize for: customer support, marketing/site
guide, lead generation, docs/help, onboarding, or a mix?
```

If the user is unavailable and the task should proceed, infer the purpose from the prompt and website, then state that assumption in the final report.

Capture:

| Input            | Example                                                    |
| ---------------- | ---------------------------------------------------------- |
| Website URL      | `https://example.com`                                      |
| Chatbot purpose  | Customer support, lead generation, documentation assistant |
| Target audience  | Customers, prospects, internal team                        |
| Support email    | `support@example.com`                                      |
| Brand preference | Friendly, formal, concise, technical                       |

## 1. Inspect the website

Use browser/fetch tools for prose understanding, but use raw HTML for structured signals such as colors, icons, manifest, and sitemap links.

```bash theme={null}
curl -sL https://example.com -o /tmp/sitegpt-page.html
```

Extract candidate colors:

```bash theme={null}
grep -oE '#[0-9a-fA-F]{6}' /tmp/sitegpt-page.html | sort | uniq -c | sort -rn | head -30
grep -oE 'name="theme-color"[^>]*' /tmp/sitegpt-page.html
```

Extract candidate icons and images:

```bash theme={null}
grep -oE '<link[^>]*rel="[^"]*icon[^"]*"[^>]*' /tmp/sitegpt-page.html
grep -oE '<link[^>]*apple-touch[^>]*' /tmp/sitegpt-page.html
grep -oE '<link[^>]*manifest[^>]*' /tmp/sitegpt-page.html
grep -oE 'property="og:image"[^>]*content="[^"]*"' /tmp/sitegpt-page.html
```

Look for sitemap hints:

```bash theme={null}
curl -sL https://example.com/robots.txt
curl -I https://example.com/sitemap.xml
```

Capture:

* Brand/product name
* Value proposition
* Support topics
* Docs/pricing/contact URLs
* Best brand color, preferably from raw HTML, CSS variables, manifest, or a prominent CTA
* Best icon/logo file, preferably `apple-touch-icon`, a logo PNG, or a clean square icon
* Sitemap URL if available

<Warning>
  Do not choose a generic color like `#2563EB` unless the site actually uses it.
  If color or icon falls back to a default, treat setup as incomplete and
  inspect raw HTML/assets again.
</Warning>

## 2. Start onboarding or create the chatbot

### Agent-first onboarding

```bash theme={null}
sitegpt onboarding start https://example.com --agent-name "<agent-name>" --json
```

Save the returned values:

```bash theme={null}
WORKSPACE_ID=<data.workspace.id>
CHATBOT_ID=<data.workspace.chatbotId>
export SITEGPT_API_TOKEN=<data.apiToken>
```

The export is optional, but it keeps the rest of this playbook readable. If you do not export it, prefix each setup command with `SITEGPT_API_TOKEN=<temporary-token>`.

Check the onboarding workspace:

```bash theme={null}
sitegpt onboarding status $WORKSPACE_ID --json
```

### Existing account

```bash theme={null}
sitegpt chatbots create "Example Support" \
  --description "Answers customer questions about Example products, pricing, documentation, and support." \
  --json
```

Save the returned chatbot ID:

```bash theme={null}
CHATBOT_ID=<returned-chatbot-id>
```

Skip this create command for onboarding because `onboarding start` already created the temporary chatbot.

## 3. Add knowledge

Prefer a sitemap when available because it usually gives cleaner coverage than a blind crawl.

<Tabs>
  <Tab title="Sitemap preferred">
    ```bash theme={null}
    sitegpt knowledge sitemap add \
      --chatbot $CHATBOT_ID \
      https://example.com/sitemap.xml \
      --max-links 500 \
      --only-main-content true \
      --sync WEEKLY \
      --scan WEEKLY \
      --json
    ```
  </Tab>

  <Tab title="Website crawl fallback">
    ```bash theme={null}
    sitegpt knowledge website add \
      --chatbot $CHATBOT_ID \
      https://example.com \
      --depth 3 \
      --max-links 200 \
      --only-main-content true \
      --json
    ```
  </Tab>

  <Tab title="Selected links">
    ```bash theme={null}
    sitegpt knowledge links add \
      --chatbot $CHATBOT_ID \
      https://example.com/pricing \
      https://example.com/docs \
      https://example.com/contact \
      --only-main-content true \
      --json
    ```
  </Tab>
</Tabs>

If the website has noisy navigation, cookie banners, or repeated layout blocks, add selectors:

```bash theme={null}
sitegpt knowledge website add \
  --chatbot $CHATBOT_ID \
  https://example.com \
  --include-selector main \
  --exclude-selector nav \
  --exclude-selector footer \
  --only-main-content true
```

## 4. Download and upload brand assets

Download the chosen icon/logo to a local file:

```bash theme={null}
curl -sL https://example.com/logo-icon.png -o /tmp/sitegpt-logo.png
file /tmp/sitegpt-logo.png
```

Upload it as the bot icon and chat bubble icon when it is suitable:

```bash theme={null}
sitegpt icons upload --chatbot $CHATBOT_ID bot /tmp/sitegpt-logo.png
sitegpt icons upload --chatbot $CHATBOT_ID chat-bubble /tmp/sitegpt-logo.png
```

If the source icon is tiny or visually poor, use the best clean logo mark available rather than a blurry favicon.

## 5. Configure appearance

Use the extracted brand color and readable contrast.

```bash theme={null}
sitegpt settings appearance update \
  --chatbot $CHATBOT_ID \
  --title "Example Support" \
  --welcome "Hi! I can help with Example products, pricing, documentation, and support." \
  --placeholder "Ask about Example..." \
  --brand-color "#F43F5E" \
  --brand-text-color "#FFFFFF" \
  --link-color "#F43F5E" \
  --icon-shape CIRCLE \
  --icon-position RIGHT
```

## 6. Create persona

Write persona text to a temporary file:

```bash theme={null}
cat > /tmp/sitegpt-persona.md <<'EOF'
You are Example's helpful customer support assistant.
Use a clear, friendly, and practical tone.
Prioritize accurate answers from SiteGPT knowledge.
When the visitor asks about pricing, support, integrations, setup, or troubleshooting, answer directly and offer the most relevant next step.
EOF
```

Create and activate it:

```bash theme={null}
sitegpt personas add --chatbot $CHATBOT_ID --title "Example support specialist" --file /tmp/sitegpt-persona.md --json
sitegpt personas use --chatbot $CHATBOT_ID <persona-id>
```

## 7. Create instructions

```bash theme={null}
cat > /tmp/sitegpt-instructions.md <<'EOF'
Answer using the chatbot knowledge first.
If the answer is not available in the knowledge base, say that you do not have enough information and suggest contacting support.
Keep answers concise unless the visitor asks for detail.
Do not invent prices, policies, or guarantees.
When useful, suggest a follow-up question the visitor can ask next.
EOF
```

```bash theme={null}
sitegpt instructions add --chatbot $CHATBOT_ID --title "Grounded support instructions" --file /tmp/sitegpt-instructions.md --temperature 0.3 --json
sitegpt instructions use --chatbot $CHATBOT_ID <instruction-id>
```

## 8. Add starters and followups

Create conversation starters from the website's main user intents:

```bash theme={null}
sitegpt starters add --chatbot $CHATBOT_ID --title "What can you help with?" --message "What can you help me with?"
sitegpt starters add --chatbot $CHATBOT_ID --title "Pricing" --message "Tell me about pricing."
sitegpt starters add --chatbot $CHATBOT_ID --title "Getting started" --message "How do I get started?"
```

Create followups:

```bash theme={null}
sitegpt followups add --chatbot $CHATBOT_ID --title "Talk to support" --escalation
sitegpt followups add --chatbot $CHATBOT_ID --title "View docs" --link https://example.com/docs --type LINK
sitegpt followups add --chatbot $CHATBOT_ID --title "Compare plans" --message "Can you compare the plans?"
```

## 9. Configure lead and support settings when relevant

For lead-generation sites:

```bash theme={null}
sitegpt settings lead-form update \
  --chatbot $CHATBOT_ID \
  --enabled true \
  --collect-name true \
  --collect-phone true \
  --trigger intent \
  --notification-email sales@example.com
```

For support-heavy sites:

```bash theme={null}
sitegpt settings human-support update \
  --chatbot $CHATBOT_ID \
  --enabled true \
  --request-prompt "Would you like me to connect you with support?" \
  --notification-email support@example.com
```

## 10. Verify the chatbot

```bash theme={null}
sitegpt dashboard --chatbot $CHATBOT_ID --json
sitegpt knowledge documents list --chatbot $CHATBOT_ID --json
sitegpt messages send --chatbot $CHATBOT_ID "What can you help me with?" --json
sitegpt messages send --chatbot $CHATBOT_ID "How do I contact support?" --json
```

Check for failed documents:

```bash theme={null}
sitegpt knowledge documents list --chatbot $CHATBOT_ID --status FAILED --json
```

If failures exist:

```bash theme={null}
sitegpt knowledge documents resync --chatbot $CHATBOT_ID --state failed
```

For onboarding, also inspect the setup checklist:

```bash theme={null}
sitegpt onboarding status $WORKSPACE_ID --json
```

Fix `PENDING`, `WARNING`, or `UNKNOWN` checklist items when possible before sharing the onboarding URL.

## 11. Share or claim

For existing-account setup, give the user the dashboard link:

```bash theme={null}
sitegpt dashboard --chatbot $CHATBOT_ID
```

For agent-first onboarding, give the user the onboarding URL returned by `onboarding start` after the chatbot is useful. If the user wants to claim it, ask for email, plan, and interval:

```bash theme={null}
sitegpt onboarding claim $WORKSPACE_ID \
  --email user@example.com \
  --plan GROWTH \
  --interval MONTH \
  --json
```

Plans are `STARTER`, `GROWTH`, and `SCALE`. Intervals are `MONTH` and `YEAR`.

## Quality bar

Before calling the setup complete, confirm:

* Chatbot title and description match the website.
* Knowledge was added from sitemap, website crawl, links, files, or text.
* Brand color is extracted from the real site, not guessed.
* Bot/chat bubble icon is uploaded when a suitable brand asset exists.
* Persona and instructions are active.
* Starters and followups match likely visitor questions.
* Lead/human support settings match the user's goal.
* At least one test message returns a useful answer.
* `dashboard` and `documents list` show no obvious setup failures.

## Parallelization guidance

Agents can parallelize independent discovery tasks:

* Fetch raw HTML, `robots.txt`, and `sitemap.xml`.
* Inspect prose/content in a browser while raw HTML is searched for assets.
* Download candidate icons while creating persona/instruction drafts.
* After chatbot creation, add knowledge, upload icons, and prepare settings in parallel when the CLI environment supports safe concurrent commands.

Do not parallelize commands that depend on returned IDs, such as `personas use` before `personas add` returns a persona ID.