AI chat

Every WPTom template has a chat button on every page. A visitor asks a question and the answer streams in, written by Claude (or an OpenAI model) from your own content: your services and prices, your products, events or docs, your opening hours, your journal. It doesn’t make things up from the web, and you decide how it answers.

Templates: all of them. Service: Claude by Anthropic, or OpenAI, both paid per use. You need one of them.

Provider	Setting	Default model
Claude (Anthropic)	`ANTHROPIC_API_KEY`	`claude-haiku-5-5`
OpenAI	`OPENAI_API_KEY`	`gpt-5-mini`

If both keys are set, the chat uses Claude. CHAT_MODEL changes the model of whichever provider is in use. Templates that don’t list OPENAI_API_KEY in their .env.example yet support Claude only; npx wptom update brings the newer version.

How it works

The chat button opens a panel. Its script downloads only when someone opens it, so it costs your pages nothing until then.
The panel talks to your site’s own route, /api/chat, which runs on the server and calls Claude or OpenAI with your key. The key never reaches the browser.
Each answer is based on two things: the assistant instructions you write in the content editor, and your content, which the template adds automatically (see What it knows).

Without a key

The chat button still shows. When a visitor opens the panel, it says the chat isn’t connected yet (the texts are in Interface texts → AI chat, “Not connected” title and text). Nothing is sent anywhere.

1. Create a key

Pick one provider. Claude is the default the instructions and limits were tuned with; OpenAI works the same way.

Claude (Anthropic)

Go to console.anthropic.com and create an account (or sign in).
Add a payment method and buy credits under Billing (the API is paid per use).
Set a monthly spend limit under Limits. The chat has its own brakes (below), but a spend limit is the one that protects your bill.
Open API Keys → Create Key, give it a name (e.g. my-site) and copy it. It starts with sk-ant-. You see it only once.

OpenAI

Go to platform.openai.com and create an account (or sign in).
Add a payment method and credits under Settings → Billing.
Set a monthly budget under Settings → Limits.
Open API keys → Create new secret key, give it a name and copy it. It starts with sk-. You see it only once.

2. Add it to `.env`

With Claude:

ANTHROPIC_API_KEY=sk-ant-...
CHAT_MODEL=

With OpenAI:

ANTHROPIC_API_KEY=
OPENAI_API_KEY=sk-...
CHAT_MODEL=

ANTHROPIC_API_KEY or OPENAI_API_KEY: the key you just copied. Set one. If both are set, Claude is used and the OpenAI key is ignored.
CHAT_MODEL: optional, and it applies to the provider in use. Leave it empty for the default: claude-haiku-5-5 with Claude, gpt-5-mini with OpenAI, both fast and inexpensive models that suit short answers. To use another model, put its model id from the provider’s model list here (a Claude id with Claude, an OpenAI id with OpenAI).

Restart npm run dev.

3. Try it on your computer

Open your site at the address npm run dev printed.
Click the chat button (it floats at the bottom right) and pick one of the suggested questions, or type your own, e.g. a question about a price on your site.
You should see the answer appear word by word within a few seconds, using facts from your content.
Ask something your content doesn’t cover. With the default instructions, the assistant says it doesn’t know and points to a page instead of inventing an answer.

To check the connection without the panel, add /api/chat to that address in the browser: it shows {"enabled":true} with a key and {"enabled":false} without one.

Each question is billed by your provider: Anthropic shows the usage in the Console under Usage, OpenAI on the platform’s Usage page.

4. Put it online

In Vercel, Settings → Environment Variables: add ANTHROPIC_API_KEY or OPENAI_API_KEY (and CHAT_MODEL if you set it).
Redeploy.
Open the live site and ask one question to check.

What it knows

The chat receives, with every question:

Your assistant instructions: Interface texts → AI chat → Assistant instructions in the content editor. This is where you set the tone, what to answer and what not, and where to send people. {name} and {description} are replaced with your site’s name and description from Site settings.
Your content, added automatically by src/lib/chat-knowledge.ts. What exactly depends on the template; the field’s description in the editor says it, for example:

Template	Added automatically
Aurora	Docs, FAQ and pricing
Handy, Kelvin	Services, prices, jobs, areas and tips
Mint	Treatments, prices, team, opening hours and journal
Encore	Lineup, programme, tickets, info and news
Wag, Whisker	The animals, how to adopt, ways to help, visiting and the stories

The other templates follow the same idea for their own content. Change a price or add a post, and the chat knows it after the next deploy.

Change what it says

Tone and rules: edit the assistant instructions. Keep the line that tells it to use only the knowledge below and to say when it doesn’t know: that is what stops it from inventing prices or dates.
Greeting, suggested questions, button and panel texts: same place, Interface texts → AI chat.
What content it receives: edit src/lib/chat-knowledge.ts. Each block (for example <prices> or <services>) is built from one part of your content; remove a block to leave it out, or add your own text block.

Limits built in

These are set in the code (@wptom/ai-chat) and protect against abuse:

Limit	Value
Questions per visitor	12 per minute (by IP address). After that the panel shows the “rate limited” text
Conversation length	The last 20 messages are sent; older ones are dropped
Message length	Longer messages are cut at 2,000 characters
Answer length	At most 2,048 tokens; the instructions ask for short answers

The per-minute limit is kept in the server’s memory, per server instance: it is a brake, not a guarantee. Your spend limit at the provider (Anthropic Console or OpenAI’s limits page) is the real cap.

Your instructions and knowledge are sent with every question. With Claude, the template marks them for Anthropic’s prompt caching, which can make questions that follow each other cheaper. OpenAI applies its own caching automatically where the model supports it.

Turn it off

The chat is added to every page in src/layouts/Base.astro. To remove it:

Open src/layouts/Base.astro and delete the line <ChatWidget /> (and its import line at the top).
Optionally delete src/pages/api/chat.ts and src/lib/chat-knowledge.ts.
Remove the ANTHROPIC_API_KEY (or OPENAI_API_KEY) variable in Vercel and redeploy.

To pause it without touching code, remove the key in Vercel and redeploy: the panel then says it isn’t connected.

Troubleshooting

What you see	Why, and what to do
“Isn’t connected” even though the key is in `.env`	The dev server was started before you added it. Restart `npm run dev`. Online: the variable is missing in Vercel, or you haven’t redeployed since adding it
The “something went wrong” text	The provider couldn’t be reached with your key. The terminal (or Vercel → your deployment → Logs) shows `[chat] provider failed` with the reason: a wrong or revoked key, no credits left, the spend limit reached, or an unknown `CHAT_MODEL` (OpenAI errors start with `OpenAI 401`, `OpenAI 404` and so on)
You set an OpenAI key, but Claude answers (or the Anthropic bill grows)	`ANTHROPIC_API_KEY` is set too, and Claude wins. Empty it in `.env` and in Vercel
`CHAT_MODEL` is ignored or fails after switching provider	The model id belongs to the other provider. Change it, or empty it to use the default
The “too many questions” text	The visitor sent more than 12 questions in a minute. It clears by itself after a minute
Answers mention old prices	The knowledge is built from the content of the deployed site. Redeploy after editing content
Answers are long or off-topic	Tighten the assistant instructions (e.g. “two to four sentences”, “only questions about our services”)