Skip to content

Developer docs

Website chat widget

A chat bubble for your website, powered by your agent. One line of HTML, nothing to install, and no secret in the visitor’s browser.

Add it to your site

In the dashboard open Widget, list the websites allowed to show it and save. You get a ready-made snippet; paste it before the closing </body> tag of every page that should show the chat.

HTML
Embed snippet (HTML)<script src="https://api.havenai.world/widget.js" data-widget-id="wid_your_widget_id" async></script>

Use the exact snippet from your dashboard; it contains your own widget id.

How it works

  • A small launcher button opens a full-screen panel on phones and a corner panel on desktop. It runs in a sealed container, so your page’s styles can’t break it and it can’t break your page.
  • Replies stream in as they are written. When the agent hands the visitor over to a person, a notice appears.
  • If the service is unavailable, no button is shown, so visitors never see a broken chat.
  • Pictures and PDFs. A paperclip lets visitors attach up to 3 pictures (PNG, JPG, WebP, GIF) or PDFs to a message, 5 MB each. The agent reads them, and can check them for edits, forgery and AI-generated images. You can switch uploads off in the widget settings.

Stop, edit and Seen

Visitors are not stuck with a message they got wrong. While the agent is answering, the send button turns into Stop: the answer ends where it is, and the words already written stay on screen, marked “Stopped”. Sending a new message while an answer is still being written stops that answer first.

A visitor who made a mistake can press Edit under their last message, correct it and save. The agent answers the corrected message and the old answer is replaced. It is still kept in the conversation record, marked “Replaced”.

Under a visitor’s message the chat shows “Sent”, then “Seen 14:32” once the agent (or a person on your team) has read it. You can switch the Seen line off in the widget settings; Stop and Edit always stay on.

Stop ends the answer, not what the agent already did

If the agent had already done something before the visitor pressed Stop, for example opened a ticket, that cannot be undone.

Security

The widget id is public, and that is fine

It only says whose chat to open. It cannot be used to read your data or to act on your account.
  • Allowed websites only. The widget works only on the websites you list (https, except localhost for testing). On any other site it is refused with origin_not_allowed.
  • Short-lived visitor tokens. Each visitor gets a temporary token tied to your website. It is not a cookie and never an API key.
  • Public information only. Visitors can reach only the read-only tools you marked public. Tools that change things are never available to widget visitors. Order details appear only after the visitor proves the order number and email match.
  • Cost limits. You set the maximum message length and a daily message cap, and there are per-visitor and per-network limits. Your plan’s message allowance still applies.
  • Optional bot check. You can require a challenge before a chat starts.
  • Safe uploads. Files are recognised by their contents, not their name; only pictures and PDFs are accepted; each visitor, each network address and each business has an hourly or daily limit; and files are never shown to other visitors. Uploads belong to the visitor’s chat and are deleted with the conversation.

If it doesn’t show

  • The page’s address is not on the allowed list. Add it exactly, including https:// and www. if you use it.
  • The agent is paused or out of messages. Visitors see a neutral “chat is unavailable” message (chat_unavailable), never your billing details.
  • Your daily widget cap was reached (widget_cap_reached). It resets on a rolling 24-hour basis.