How to add a chatbot to your website (widget and API)
Updated: · 7 min read
In short
To add a chatbot to your website, you have two options. The widget is a single line of code that you paste into your pages, and it shows a chat bubble to visitors. The API lets developers call the bot from their own server or app. Either way, restrict the widget to your domains and never put an API key in public code.
You can add a chatbot to your website in a few minutes once the bot itself is ready. The two common routes are a ready-made chat widget, which needs one line of code, and a chatbot API, which gives developers full control over the interface. This guide explains both with Ravano as the example. It covers where to paste the code, how to restrict it to your own domains, how to customise the look, how to test, and what to check if the bubble does not appear. It also covers the most important security rule: keep your API key off the browser.
Before you start: get the bot ready first
Installing is the last step, not the first. A chat bubble on your site is only useful if the bot behind it answers correctly. In Ravano the order is: add your sources (website, files, channels), review and approve what the bot learned, set its persona and tone, and then install.
Test the bot inside the panel first. Building and testing there is free, so you can ask it real customer questions and fix gaps before any visitor sees it. If you have not built a bot yet, start with the guide on how to build a chatbot for your website.
Widget or API: which one should you pick?
Pick the widget if you want a working chat bubble with the least effort. Pick the API if you already have an app, a mobile product or a custom chat screen and want to control the design and the flow yourself.
| Website widget | API | |
|---|---|---|
| Effort | Paste one line of code | Build your own chat interface and a small backend |
| Who does it | Anyone who can edit the site | A developer |
| Look and feel | Colour, title and position settings | Fully yours |
| Best for | Company sites, shops, blogs | Apps, internal tools, custom experiences |
| Access control | Restrict to your own domains | Protected by an API key kept on your server |
Install the widget with one line of code
The widget is a short script tag. You copy it from the Install page of your Ravano panel and paste it into your site. The exact snippet, including your own key, is shown there; the shape looks like this:
<script src="https://YOUR-API-HOST/widget.js" data-key="YOUR_WIDGET_KEY" async></script>Where to paste the snippet
- Hand-written or custom HTML: paste it just before the closing body tag of the page, or into a shared footer file so it appears on every page.
- Content management systems: look for a setting that adds custom code to the footer or to the whole site, and paste the snippet there.
- Site builders: most have a custom code or embed area in the site settings. Use the option that applies to all pages, not a single page.
- Someone else manages your site: send them the same snippet.
The widget is a one-time purchase
The site widget is a one-time add-on of 1,490,000 Toman, paid from your wallet. After that you pay only per request, 650 Toman each. The panel keeps the widget locked until you buy it, which is why you test in the panel first. Details are on the pricing page.
Restrict domains and customise the look
Two settings are worth a minute each before you go live. Both are on the Install page.
Allowed domains
Add the domains where the widget is allowed to run, such as your main site and your shop sub-domain. If someone copies your snippet onto a site you do not own, the widget should not work there. This keeps other people from spending your wallet.
Colour, title, position and launcher text
Choose a brand colour, a title that visitors will recognise, and the side of the screen where the bubble sits. Ravano supports both right-to-left and left-to-right layouts, so pick the position that matches yours.
Test before you tell anyone
Run through this short checklist on the live site, ideally on a phone and a computer:
- Open a normal browser window and confirm the bubble appears on the pages you expect.
- Ask three or four real questions that customers actually send. Check that each answer is correct and shows its source.
- Ask something your information does not cover. The bot should say it does not know or hand off, not invent an answer.
- Check a small screen: the bubble should not cover buttons such as checkout.
- Open the site from a domain that is not on your allowed list, if you can, and confirm the widget does not work there.
Use the chatbot API for custom apps
If you are a developer, the API lets you send a customer message and get the bot's answer back. You create an API key in the panel, then call the endpoint from your own server. The request is a POST to /api/v1/public/v1/chat with an Authorization header and a small JSON body containing the message and a user_id that identifies your customer.
curl -X POST https://YOUR-API-HOST/api/v1/public/v1/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "How long does delivery take?",
"user_id": "customer-42"
}'What comes back
The response includes a conversation_id, which you reuse to keep a conversation together, and a message object. Read message.content for the answer text and message.citations for the sources behind it. Show the sources to your users if you can; it builds trust.
Streaming answers
For a chat that feels live, the API can stream the answer as it is written instead of waiting for the whole reply. See the documentation for the streaming format and more code samples.
Security: keep your API key off the browser
An API key is a password for spending your wallet. If you place it in JavaScript that runs in a visitor's browser, anyone can open the developer tools, copy it and use it.
- For a website, use the widget. It is built to run in the browser and can be limited to your domains.
- For a custom front end, call your own backend from the browser, and let your backend call the Ravano API with the key stored as a server-side secret.
- Never commit keys to a public repository, and create a new key if you suspect one has leaked.
- Add your own rate limits on your backend so one visitor cannot flood the bot.
Troubleshooting checklist
If the bubble does not show up or the bot does not answer, work through these in order:
- The widget is still locked: confirm the add-on has been bought for this business.
- The snippet is missing or was pasted in the wrong place: view the page source and search for the widget script.
- The domain is not allowed: check that the exact domain, including any www or sub-domain, is in your allowed list.
- A cache is serving an old page: clear the site cache or your CDN cache and reload.
- The wallet is empty: real requests need balance, so top up and try again.
- The bot gives poor answers: that is an information problem, not an install problem. Check the unanswered questions list and add or fix sources.
A note on privacy, and your next step
Chatbots handle real customer messages, so be open about it. Tell visitors they are talking to an automated assistant, avoid asking for sensitive details such as full card numbers in chat, and mention the bot in your privacy policy.
Ready to put a bot on your site? Create a free account, build and test the bot at no cost, then follow the steps above. If you are comparing options first, read the chatbot cost guide or learn how answers are grounded.
Frequently asked questions
How do I add a chatbot to my website?
Build and test your bot first, then copy the one-line widget snippet from the Install page and paste it into your site, ideally in a footer shared by all pages. Restrict it to your own domains, check the look on mobile, and test with real questions.
Do I need a developer to install a chatbot widget?
Usually not. If you can edit your site's footer or custom code area, you can paste the one-line snippet yourself. If someone else manages your site, send them the same snippet. A developer is only needed if you want the API and a custom chat interface.
Is it safe to put my chatbot API key in website code?
No. Anything in browser code can be read and copied, and the key spends your wallet. Use the widget for websites, or call your own backend and keep the API key there as a server-side secret. Replace any key that may have leaked.
Can I limit the chatbot widget to my own domains?
Yes. In Ravano you list the domains where the widget may run. If someone copies your snippet to another site, it should not work there, which protects your wallet from misuse. Remember to include sub-domains such as shop or www if you use them.
Why is my chatbot widget not showing?
Common causes are a locked widget, a snippet pasted in the wrong place, a domain missing from the allowed list, or a cached page. Check the page source for the script, clear caches, and try a private window to rule out browser extensions.
