Set up a chatbot in an existing account

Use this playbook when the user already uses SiteGPT, gives you a token or profile, or asks you to create or update a chatbot in their account. This is a live account. Read the current state before you change anything.

Before you start

Plan: the Growth plan or above for CLI access. See Plans and limits.
CLI: installed. See Install and log in.
Access: a CLI login. sitegpt login with no --scope gives standard access, which includes every scope in this playbook. Your role limits what a token can do. See Authentication.
Input: the website URL, the chatbot purpose, and whether to create a new chatbot or update an existing one. See Ask for the purpose first.

To use a narrower token, request only these scopes:

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 \
  --scope conversations:write

conversations:write lets you send test messages. Add the matching :delete scopes only if you must delete mistakes.

Steps

Check the account

sitegpt whoami --json

If this fails because you are not logged in, run sitegpt login. If the user names an account or environment, switch to its profile:

sitegpt profiles list
sitegpt profiles use <profile>

Create or select the chatbot

List the chatbots first:

sitegpt chatbots list --json

To update a chatbot, save its ID and read it:

CHATBOT_ID=<chatbot-id>
sitegpt chatbots get $CHATBOT_ID --json

To create a chatbot, run the command below and save the returned ID as CHATBOT_ID. Do not create a duplicate unless the user asked for a new chatbot.

sitegpt chatbots create "<Brand> Support" \
  --description "Answers questions about <Brand> products, pricing, docs, and support." \
  --json

Read the website

Use a browser or fetch tool to read the text. Use raw HTML to find colors, icons, and the sitemap.

curl -sL https://example.com -o /tmp/sitegpt-page.html
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
grep -oE '<link[^>]*rel="[^"]*icon[^"]*"[^>]*' /tmp/sitegpt-page.html
grep -oE '<link[^>]*apple-touch[^>]*' /tmp/sitegpt-page.html
curl -I https://example.com/sitemap.xml

Write down the brand name, what the product does, the main URLs, the support and sales emails, the sitemap URL, the brand color, and the best square logo. Do not invent company facts, prices, policies, or emails.

Add content

For an existing chatbot, list the current content first:

sitegpt knowledge documents list --chatbot $CHATBOT_ID --json
sitegpt knowledge sync-jobs list --chatbot $CHATBOT_ID --json

Add only the sources that are missing. Do not delete, disable, or resync all content unless the user asks.For a new chatbot, add the sitemap. Use a website crawl if the site has no sitemap. See the command reference for crawl options.

sitegpt knowledge sitemap add \
  --chatbot $CHATBOT_ID \
  https://example.com/sitemap.xml \
  --max-links 500 \
  --only-main-content true \
  --sync MONTHLY \
  --scan DAILY \
  --json

If the plan does not include a frequency, SiteGPT sets it to NEVER and adds a warning to the response. Tell the user about each warning. Auto-sync works only for website, sitemap, and GitHub sources. Scan works only for sitemap sources.If pages have a lot of menus or footers, add CSS selectors, for example --include-selector main --exclude-selector nav --exclude-selector footer.

Set the appearance and icons

For an existing chatbot, read the current settings first. Keep the user’s brand choices unless they asked for a change.

sitegpt settings appearance get --chatbot $CHATBOT_ID
sitegpt settings general get --chatbot $CHATBOT_ID

For a new chatbot, apply the brand color:

sitegpt settings appearance update \
  --chatbot $CHATBOT_ID \
  --title "<Brand> Support" \
  --welcome "Hi! I can help with <Brand> questions." \
  --placeholder "Ask about <Brand>..." \
  --brand-color "#0F766E" \
  --brand-text-color "#FFFFFF" \
  --link-color "#0F766E" \
  --icon-position RIGHT

Download the logo to a local file, then upload it. The CLI uploads local files only.

curl -sL https://example.com/logo-icon.png -o /tmp/sitegpt-logo.png
sitegpt icons upload --chatbot $CHATBOT_ID bot /tmp/sitegpt-logo.png
sitegpt icons upload --chatbot $CHATBOT_ID chat-bubble /tmp/sitegpt-logo.png

Set the persona

For an existing chatbot, list the personas first. Do not replace a persona that the user tuned unless they approve.

sitegpt personas list --chatbot $CHATBOT_ID --json

For a new chatbot, write a persona file, add it, and select it:

cat > /tmp/sitegpt-persona.md <<'EOF'
You are the <Brand> support assistant.
Use a clear, friendly, and practical tone.
Answer from the chatbot content first.
Offer the most useful next step.
EOF
sitegpt personas add --chatbot $CHATBOT_ID --title "<Brand> support specialist" --file /tmp/sitegpt-persona.md --json
sitegpt personas use --chatbot $CHATBOT_ID <persona-id>

Set the instructions

For an existing chatbot, list the instructions first. Keep the selected instructions unless the task is to replace them.

sitegpt instructions list --chatbot $CHATBOT_ID --json

For a new chatbot:

cat > /tmp/sitegpt-instructions.md <<'EOF'
Answer from the chatbot content first.
If the content does not have the answer, say so and suggest how to contact support.
Do not invent prices, policies, or guarantees.
Keep answers short unless the visitor asks for detail.
EOF
sitegpt instructions add \
  --chatbot $CHATBOT_ID \
  --title "Grounded <Brand> assistant" \
  --file /tmp/sitegpt-instructions.md \
  --temperature 0.3 \
  --json
sitegpt instructions use --chatbot $CHATBOT_ID <instruction-id>

Add conversation starters and follow-up suggestions

For an existing chatbot, list them first. Add missing ones or improve old ones. Do not delete any without approval.

sitegpt starters list --chatbot $CHATBOT_ID --json
sitegpt followups list --chatbot $CHATBOT_ID --json

For a new chatbot, add 3 to 5 of each:

sitegpt starters add --chatbot $CHATBOT_ID --title "What does <Brand> do?" --message "What does <Brand> do?" --json
sitegpt starters add --chatbot $CHATBOT_ID --title "Pricing" --message "Tell me about pricing and plans." --json
sitegpt starters add --chatbot $CHATBOT_ID --title "Getting started" --message "How do I get started?" --json
sitegpt followups add --chatbot $CHATBOT_ID --title "Talk to support" --message "I want to talk to a person." --escalation
sitegpt followups add --chatbot $CHATBOT_ID --title "View docs" --link https://example.com/docs --type LINK

Set lead and human support options, if the purpose needs them

For an existing chatbot, read the current settings first. Do not change who gets notified unless the user asks.

sitegpt settings lead-form get --chatbot $CHATBOT_ID
sitegpt settings human-support get --chatbot $CHATBOT_ID

For lead generation:

sitegpt settings lead-form update \
  --chatbot $CHATBOT_ID \
  --enabled true \
  --collect-name true \
  --trigger intent \
  --notification-email sales@example.com

For customer support:

sitegpt settings general update --chatbot $CHATBOT_ID --support-email support@example.com
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

Check that it works

Wait until the content finishes training, then check for failed documents:

sitegpt knowledge wait --chatbot $CHATBOT_ID
sitegpt knowledge documents list --chatbot $CHATBOT_ID --status FAILED --json

If documents failed, resync them:

sitegpt knowledge documents resync --chatbot $CHATBOT_ID --state failed

Send realistic visitor questions:

sitegpt messages send --chatbot $CHATBOT_ID "What does this company do?" --json
sitegpt messages send --chatbot $CHATBOT_ID "How much does it cost?" --json
sitegpt messages send --chatbot $CHATBOT_ID "How can I contact support?" --json

Each answer should use facts from the website.

Show the summary and the install code:
sitegpt dashboard --chatbot $CHATBOT_ID sitegpt installation snippet --chatbot $CHATBOT_ID
The dashboard summary shows the training state, document counts, and the chat URL.

Hand back to the human

Report:

The chatbot ID and the chat URL. The chatbot is also in the user’s SiteGPT dashboard.
The purpose, and any purpose you inferred.
The content you added, and any failed documents.
What you changed in the persona, instructions, conversation starters, follow-up suggestions, appearance, and icons.
Every warning the CLI returned, such as a sync frequency set to NEVER.
The install code, if the user asked for it. See Add the chatbot to your website.
Changes that you did not make because they need the user’s approval.

Get started

Chatbot setup

Operations

Agent playbooks

Reference

Set up a chatbot in an existing account

Before you start

Steps

Check that it works

Hand back to the human

​Before you start

​Steps

​Check that it works

​Hand back to the human

Before you start

Steps

Check that it works

Hand back to the human