Web chat widget

The chat widget is a small button on your website that opens the conversation window. Each project has its own widget.

Install

Copy the snippet from Project settings → Widget and paste it before the closing </body> tag of your website:

<script>window.Commelia=window.Commelia||function(){(Commelia.q=Commelia.q||[]).push(arguments)};</script>
<script src="https://api.commelia.com/widget/loader.js" data-project="pk_..." async></script>

Use Open test page to try it before it goes live. Under Allowed websites, list the origins that may embed the chat (one per line, e.g. https://www.example.org). Leave it empty to allow every website.

You can control the widget from your page:

Commelia("setLocale", "de"); // show the widget in German
Commelia("open");            // open the chat, e.g. from a "Chat with us" button

Branding and wording

• Branding (General tab): primary color, font (from Google Fonts), logo and position (bottom left or right).
• Wording (Localization tab): replace the greeting, subtitle, start button, placeholder and online/offline status texts, and the texts visitors see when they end a conversation. The transcript email is worded in the same tab under Messages to visitors.
• Languages (General tab): the languages your widget is offered in. English and German have built-in texts; for other languages, write the texts under Localization or translate them automatically from the first language.

Intro questions

Intro questions are asked before the first message, for example age group, postcode or topic. Questions can be free text, a choice or an email address, and can be required. The answers are attached to the conversation, can be used to filter the inbox and to route conversations to the right group.

Opening hours and away messages

Under Opening hours (Widget tab), set weekly hours, holidays and date-specific exceptions in your timezone. Outside these hours the widget shows your away message, and visitors can leave their email address so the team can answer later. If the AI assistant runs in auto mode, you can choose whether it answers always, only outside opening hours, or whenever nobody is online.

Identifying signed-in users

If people sign in on your website, you can pass their identity so that conversations continue across devices. Compute an HMAC on your server with the project’s identity secret and pass it to the widget:

Commelia("identify", {
  userId: "42",
  email: "jane@example.org",
  name: "Jane",
  hash: "<HMAC-SHA256(identitySecret, userId) in hex, computed on your server>",
});

Keep the identity secret on your server. You can also allow only identified users to chat. Without identity, visitors stay anonymous unless they give their email address.