Aller au contenu
FR
Ouvrir l’app

For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/agent-configuration/website-widget.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.

Website Widget

10 min de lecture
Copier en Markdown
Voir en MarkdownOuvrir le fichier .md brut.md

Ce contenu n’est pas encore disponible dans votre langue.

The website widget puts your agent on your own site as a chat and voice bubble. Visitors type or talk to the same agent that answers your phone, with the same instructions, knowledge, tools and workflows. You also get a test link: a hosted page where anyone can talk to the agent, before the widget is on your site.

You can do all of it from the app, or from Claude or ChatGPT without opening the app.

  1. Turn the widget on

    Open the agent → Channels → Website Widget and switch it on. Until it is on, the test link shows This assistant isn’t available right now and the embedded widget does not load.

  2. Try the test link

    Embed & share → Shareable page link → Open. The link is https://app.voicelogica.ai/w/<agent id>. Ask the agent what callers usually ask. You can also send this link to customers by email, SMS or Viber.

  3. Add it to your website

    Embed & share → Add to your website → Copy. The code is two lines:

    <voice-logica-agent agent-id="<agent id>"></voice-logica-agent>
    <script src="https://api.voicelogica.ai/widget/embed.js" async type="text/javascript"></script>

    Paste it before </body> on every page. On WordPress, use a header and footer plugin and paste it in the footer field. On Wix, Shopify or Joomla, use the site’s custom code or footer scripts setting.

  4. Lock it to your domain

    Allowed domains: add your site’s hostname, for example example.com. Keep Also allow www. variant on if your site also answers on www.. An empty list lets any website embed your agent and use your chat sessions.

    The test link always works, whatever this list says.

  5. Make it look like your site

    Appearance sets the size, the corner of the screen, the colours and the avatar. Live preview shows the result before you save.

  6. Prove it

    Open your website in a private window, open the bubble and ask a real question. The conversation shows in Calls with its transcript and call results.

On a phone the bubble can cover a fixed bar of your site, such as a Book now button. Move it on phones only, without changing where it sits on computers:

  1. Open the agent → Channels → Website Widget → Appearance → Position on phones.
  2. Gap from the bottom/top on phones: how many pixels the bubble sits above the bottom edge (or below the top). A typical fixed bar is 60–90 px high, so start with the bar’s height plus 10–20 px, e.g. 90.
  3. Optional: Gap from the side on phones (pixels from the left or right edge) and Corner on phones, to move it to another corner on phones only.
  4. Turn on Preview on a phone to check it, then Save. Open your site on a phone (or in the browser’s phone view) and reload.

It applies to screens up to 767 px wide. Leave a field empty (Same as on computers) to keep the computer setting for it.

A typed chat carries on across the pages of your site, with its history, until the visitor presses End chat or stops writing for longer than Inactivity (minimum 30 minutes). On the next page the widget stays as the visitor left it: collapsed if they collapsed it, open if it was open. It is the same chat, so it uses one chat session, not one per page.

A button on your page can open the widget and ask the agent something, for example Summarise this article on a blog post. It continues the visitor’s chat if one is running and starts one only if none is.

<button onclick="window.dispatchEvent(new CustomEvent('voicelogica:ask', {
detail: { text: 'Summarise this article', url: location.href }
}))">Ask the agent</button>
FieldWhat it does
textThe question, shown as the visitor’s message.
urlOptional. Added on its own line, so the agent knows which page the question is about.
sendOptional. false only fills the message box and lets the visitor edit and send it. Default true.
agentIdOptional. Only needed when one page has more than one widget.

With a reference to the element you can call the same thing directly: document.querySelector('voice-logica-agent').ask({ text, url }). Also .open() and .close().

If Caller verification or Terms are on, the visitor goes through them first and the question is sent right after.

For safety, a link in a reply is clickable only if its domain is on the Clickable link domains list (Website Widget → Interface). Any other link shows struck through and cannot be clicked. When the list is empty, which is the default, no link is clickable.

  • Add each domain the agent may link to, for example example.com and hihello.com. A domain matches exactly: example.com does not cover shop.example.com, so add that too.
  • Also allow www. for these domains (on by default) lets example.com also cover www.example.com.
  • Allow plain http:// links only matters for sites without https. It does not make a link clickable by itself: the domain must still be on the list.

From Claude: update_agent_settings, section widget, { "interface": { "markdownAllowedDomains": ["example.com", "hihello.com"] } }.

With Voice Logica connected, ask in plain words: “Turn on the website chat for my agent and give me the code for my site.”

  • update_agent_settings with section widget and { "enabled": true } switches it on. If you give no domains, it is locked to the website on your company profile. The answer carries the test link and the embed code.
  • get_agent_settings with section widget returns the same link and code, and the current settings.
  • test_in_browser returns the test link and the embed code, and switches the widget on if it was off.

Domains, colours, placement and pre-chat fields change the same way, for example { "allowedDomains": ["example.com"] } or { "styling": { "placement": "bottom-left" } }.

Caller verification asks for an email or mobile before the chat starts and can confirm it with a code (SMS codes work for Greek and Cypriot numbers). Turn on Actions need a verified visitor when the agent can create orders, bookings or tickets: visitors who did not verify can only ask questions.

The values reach the agent as variables, so a returning customer is recognised the same way as on the phone.

To offer only typed chat, open the agent → Widget → Behavior and turn off Voice conversations, then Save. The Start a call button and New call disappear from the widget and the shareable page, and the platform refuses voice sessions for this agent even if someone calls the widget address directly.

While the agent prepares a reply, the chat shows a bubble with animated dots and the Typing indicator text. Change that text in the agent → Widget → Text & labels → Typing indicator.

For an agent that should not take calls at all, also turn off the PIN on the test line: Try this agent → uncheck Calls with the PIN on the test line → Save. See Your first agent. An agent receives phone calls only from the numbers you connect to it, so a chat agent with no number and no PIN answers only in the widget.

One agent can answer the phone and the website chat and still behave differently on each. The agent already knows when a conversation is typed: it does not get the speech-recognition and spoken-style rules there. For your own rules, use the {{serviceType}} variable in the prompt:

Conversation{{serviceType}}
Website chat (typing), WhatsApp, Viber, Messenger, Instagrammessage
Website voice (talking in the bubble)websocket
Phone callempty

Write the rule in plain words, for example:

The conversation type is “{{serviceType}}”. If it is “message”, the customer is typing: do not ask them to spell or repeat an email, name or number they wrote, and send links and details in the chat instead of by SMS. Otherwise they are speaking: confirm an email by reading it back, or offer to send an SMS so they can write it.

On WhatsApp, Viber, Messenger and Instagram each connection also has its own channel instructions that the agent reads only on that channel.

Text chats open with the agent’s phone greeting unless you give them their own. That matters when the phone greeting has lines that only fit a call, such as “This call is recorded”. Open the agent → Instructions → Greeting, click Add a chat greeting, write the first message for chats, then Save. It is sent as written in the website chat, WhatsApp, Viber, Messenger and Instagram; phone calls and website voice keep the phone greeting. Remove it with the × and chats go back to the phone greeting.

From Claude or ChatGPT: “set the chat greeting of my agent to: Hi, I’m Joanna, the digital assistant. How can I help?”

When a visitor asks for a person, the agent can hand the same chat to a teammate. That needs Transfer on the agent and Provide chat support on the teammate. See Live Support.

One chat session covers one visitor for 24 hours, however many messages, including a handover to a teammate. When none are left, new conversations are refused until you buy a chat-sessions pack. Voice conversations in the widget use voice minutes, like a phone call, not chat sessions. See How charges work.

Why does the website widget test link say the assistant isn't available?

The website widget is off. Switch it on in Website Widget, or ask Claude to turn it on.

Why doesn't the chat widget bubble show on my website?

Check that the site’s hostname is in Allowed domains (or the list is empty), that the widget code is on the page you are looking at, and that a cache plugin is not serving an old copy of the page.

Can I put the same agent's chat widget on two websites?

Yes. Add both hostnames to Allowed domains and paste the same widget code on both sites.

Can the website chat show a form when a visitor asks for a person and nobody is available?

There is no form inside the chat. When the visitor asks for a person, Live Support offers the chat to a teammate who is online; if nobody takes it, the AI says so and takes the message in the same chat, asking one question at a time for the name, an email or phone, and what it is about. To have every such message reach your team as a task, turn on Auto-create tasks in Call results; the task carries the details the visitor gave.