Quickstart
The shortest path from an empty workspace to a working chat widget on your site. Plan on about 20 minutes of actual work, plus crawl time in the background.
The order matters: your assistant needs an AI key before it can say anything, and knowledge before it can say anything useful. Do those two first, then embed.
🎬 [Video] — end-to-end walkthrough: add an AI key, set the system prompt, crawl a site, copy the embed code, paste it, and ask the live widget a question
Before you start
Have an API key ready from one of five providers — OpenAI, Anthropic, Google Gemini, Zhipu GLM, or Moonshot Kimi — on an account with credit or a payment method attached. Promptly does not supply a model key, so this isn't optional and there's no trial exception. A key on an empty account will authenticate and then fail on the first real message.
If you don't have one yet, Supported providers says where each one is issued.
1. Add your AI key
Go to Dashboard → Settings → AI Keys and click Add your first key.
- Pick your Provider.
- Paste the API key. The eye icon lets you check what landed in the field.
- When you leave the key field, Promptly asks your provider which models that key can actually use and fills the Chat model list from the answer. The hint should read "Models loaded from your key ✓". Pick a fast, tool-capable model — that's what your visitors wait on.
- Skip Advanced for now. Planner and Background default to your chat model, which is a fine starting point.
- Click Add & verify.
Verification runs by itself. Watch the card until it shows Verified plus a green Tool calling ✓ — that combination is what makes a key usable for chat. If it lands anywhere else, Key statuses explains each outcome.
This is also where the model lives from now on. There is no separate model setting to keep in sync — see Choosing a model.
2. Set the assistant's behaviour
Go to Dashboard → Settings.
- System Prompt — who the bot is, what it's for, and how it should speak. Replace the placeholder company name with your own. This is the highest-leverage text in the whole product; Writing a system prompt is worth ten minutes.
- Fallback Message — what the bot says when it finds nothing relevant. Put a real next step in here (a support email, a contact page), because visitors will see it while your knowledge base is still thin.
- Temperature, Max Tokens, and Max History (messages) have sensible defaults. Leave them until you have a reason.
Click Save Changes.
3. Add knowledge
The bot can only answer from indexed content, so give it some. Go to Dashboard → Knowledge, click Add Item, open the URL tab and choose Crawl from URL.
Enter your site's URL and click Start Crawl. Pages are fetched, cleaned of navigation and boilerplate, chunked, embedded, and indexed automatically. You're taken to a live status page, and recent jobs stay listed under Recent Crawl Jobs on the Knowledge page.
Two things to expect on a first crawl:
- Only one crawl runs at a time. Starting a second while one is active is refused — wait for it to finish or cancel it.
- The trial crawls less deeply than a subscription — 20 pages at depth 2, against 100 pages at depth 3 once you subscribe. Point the start URL at the section that matters most rather than your homepage if your site is large.
Details and the sitemap alternative are in Web crawling & sitemaps.
🖼️ [Image] — the Add Knowledge modal with the URL tab and "Crawl from URL" sub-tab selected
While the crawl runs, use the Text tab to paste in the three or four answers you know people ask for constantly. Manual entries are usually your best-performing content, because you write them in the words customers use.
4. Style the widget and copy the embed code
Go to Dashboard → Widget for the Widget Customizer — colours, greeting, launcher position. When it looks right, open the Install Widget page.
On the Script Tag (Recommended) tab, click Copy. The snippet looks like this:
<script
src="https://YOUR-API-HOST/widget/embed.js"
data-tenant="your-tenant-slug"
data-api-key="your-widget-api-key"
data-api-base="https://YOUR-API-HOST"
data-widget-base="https://YOUR-API-HOST/widget"
async
></script>Every value is filled in for your workspace already — copy it as-is rather than retyping any part of it.
5. Paste the snippet into your site
Paste the <script> tag into your site's HTML just before the closing </body> tag, then save and publish. The Install Widget page has platform-specific instructions for plain HTML, WordPress, Shopify, Wix, Squarespace, and Webflow. For a React or single-page app, see React & SPA integration.
While you're on that page, add the domains you'll load the widget from under Allowed Domains. Requests from anywhere else are rejected — including localhost, so add that too if you want to test locally first. See Origin guard & rate limiting.
6. Test it
Open your site and look for the chat bubble in the bottom-right corner. Ask something your crawled content genuinely covers, then ask something it definitely doesn't — you should get your fallback message for the second one, not an invented answer. That's the system working correctly.
If the bubble doesn't appear, check the browser console for errors and confirm Widget enabled is on under Dashboard → Settings. If the bubble appears but every reply says the assistant is temporarily unavailable, the problem is your key, not your embed — go to Troubleshooting keys.
Then what
- Watch what people actually ask. Analytics lists Content Gaps — real questions that retrieved nothing. Each one is a manual knowledge entry waiting to be written.
- Turn on human handoff so unanswerable conversations reach a person instead of a dead end: Escalation settings.
- Connect your catalog if you sell products, so the bot can search them and render cards: Connecting a catalog.