Widget

The widget puts your Agent on your website. Visitors chat with it by text, talk to it by voice, or switch from one to the other in the same conversation. Everything is set up in the Agent's Widget tab in Envocal Studio.

Settings apply as soon as you click Save: every website that already has the widget picks them up on its next page load. You never need to change the code on your website after adding it once.

Add the widget to your websiteCopy Anchor Link

<envocal-chat agent_id="YOUR-AGENT-ID"></envocal-chat><script src="https://cdn.envocal.ai/envocal-chat.min.js" async type="text/javascript"></script>

Allowed domainsCopy Anchor Link

The widget only runs on the websites listed here. This stops other websites from copying your snippet and running your Agent at your expense.

• A domain covers all its subdomains: mysite.com also allows www.mysite.com and shop.mysite.com.
• Enter just the domain. A full address like https://www.mysite.com/contact is cleaned up to www.mysite.com.
• Wildcards (*.mysite.com) and IP addresses aren't accepted. Up to 50 domains per Agent.
• With no domains listed, the widget works in Envocal Studio only.
• Reset Default in the Widget tab resets the look and behaviour but keeps the allowed domains, so the widget keeps working on your live site.

On a website that isn't allowed, the widget shows the message "The widget settings could not be loaded. Check that this website is in the agent's allowed domains." instead of starting.

ModesCopy Anchor Link

Mode (under Behavior) decides what visitors can do:

How visitors use itCopy Anchor Link

• Opening: the widget starts minimized as a button (the trigger), unless Start open is on. With Trigger style set to Message field, the trigger is a text field, so visitors can type their first message straight away.
• Text chat: the Agent's replies stream in as they are written and can contain formatting, lists, links and code blocks with a copy button.
• Voice: the call button starts a call. The microphone button dictates a message into the text field (when Dictation is on); during a call it mutes the microphone. During a call the transcript is hidden unless Show transcript by default is on; visitors can show or hide it with the messages button in the header.
• New conversation in the header clears the chat and starts over; Minimize hides the window without ending the conversation.
• Phones and tablets: the open chat fills the whole screen, whatever the desktop size settings.
• Ending: a conversation ends after a period of inactivity, with the message "Conversation ended due to inactivity." Reloading or leaving the page also ends it.

Voice needs a secure website (https://) and the visitor's permission to use the microphone. During a call the widget keeps the visitor's screen awake.

SettingsCopy Anchor Link

All settings are in the Agent's Widget tab. Leave a field empty to use the default shown in it.

BehaviorCopy Anchor Link

LayoutCopy Anchor Link

Margins go from 0 to 120 px. On phones and tablets the open chat fills the screen, so the size settings apply to desktop only.

Theme and colorsCopy Anchor Link

Page follows the website only when the page says whether it is light or dark: a dark or light class, a data-theme (or similar) attribute, or a color-scheme of dark or light on the <html> or <body> element. Otherwise the widget is light. It follows changes live, so a website's own theme switch also switches the widget.

Text and typographyCopy Anchor Link

Orb and logoCopy Anchor Link

FontCopy Anchor Link

The widget automatically uses the same font as the website. To use a different font, enter it under Font as a CSS font-family, for example Inter, sans-serif. The website must load that font (or the visitor's device must have it installed); the widget doesn't load fonts itself.

For developersCopy Anchor Link

The settings in the Widget tab are the normal way to configure the widget. A website can also adjust it from its own code.

Tag attributesCopy Anchor Link

Attributes on the <envocal-chat> tag override the saved settings on that page. Use the setting names in lower case, with underscores where they have them:

<envocal-chat agent_id="…" theme="dark" mode="text_only" start_open="true" position="bottom-left"></envocal-chat>

Common attributes: mode (voice_and_text, voice_only, text_only), theme (light, dark, system, page), position (bottom-right, bottom-center, bottom-left), start_open, trigger_style (normal, input), font, width, height, show_transcript_during_call and z_index.

z_index sets the widget's stacking order (the CSS z-index, 39 by default). By default the widget sits above ordinary page content but below the website's own menus and dialogs, so those open on top of it, even while the chat is open. On phones the open chat fills the screen and covers everything, like a dialog. If the widget ends up behind something on your website, or in front of something it shouldn't cover, set a different value:

<envocal-chat agent_id="…" z_index="1000"></envocal-chat>

JavaScriptCopy Anchor Link

configure() changes settings while the page runs, without restarting a conversation. It overrides both the saved settings and the attributes:

const widget = document.querySelector('envocal-chat');
widget.configure({ theme: 'dark', showTranscriptDuringCall: true });

Client-side toolsCopy Anchor Link

Client-side tools are tools your website defines for the Agent. They run in the visitor's browser, so the Agent can act on the page itself: navigate to another page, fill in a form, show a product. The Agent calls them in text and voice conversations, and each tool's return value is sent back to the Agent.

Define the tools and their handlers on the element, before the visitor starts a conversation:

<envocal-chat id="envocal-widget" agent_id="…"></envocal-chat>
<script>
  const widget = document.getElementById('envocal-widget');
  widget.tools = [{
    name: 'set_name',
    description: 'Show the visitor name in the page heading when they tell you their name.',
    parameters: {
      type: 'object',
      properties: { name: { type: 'string', minLength: 1, maxLength: 100 } },
      required: ['name'],
      additionalProperties: false
    }
  }];
  widget.tool_handlers = {
    set_name: async ({ name }) => {
      document.querySelector('h1').textContent = 'Welcome ' + name;
      return { ok: true };
    }
  };
</script>
<script src="https://cdn.envocal.ai/envocal-chat.min.js" async></script>

• Only the tool definitions are sent to Envocal; the handlers stay in the page. Validate the arguments in the handler: the AI writes them.
• A handler may be async. A thrown error is reported to the Agent as a failed tool call; a handler gets 30 seconds by default.
• Tool names must be unique and can't reuse the names of the Agent's own tools.
• Changes to tools and tool_handlers apply from the next conversation.
• Up to 32 client-side tools per page.

TroubleshootingCopy Anchor Link