Web widget

The web widget lets visitors start chat conversations from your website. Conversations become tickets in Chatarmin CX.

What you can configure

widget appearance
welcome message
language
AI agent
escalation behavior
channel-specific settings

Recommended setup

Create the web channel

Go to Channels -> Web widget and create a new widget.

Customize the widget

Match the colors, copy, and greeting to your brand.

Choose the AI agent

Select the AI agent that should draft or send replies for widget tickets.

Configure handover

Decide when visitors should be handed over to a human agent.

Install the widget

Add the provided script to your website and test a conversation.

Identify visitors with website contact details

Show your support team the contact details your website already knows, such as a signed-in customer’s name and email. Pass a user object in the widget’s first window.cx_armin.init() call. Replace your existing widget installation snippet with the example below, before the closing </body> tag. Replace YOUR_WIDGET_ID with the ID from your widget’s installation snippet, and replace the example contact details with your website’s visitor data. Omit any details you do not know, or omit user for anonymous visitors.

<script>
  ;(function (d, t) {
    var v = d.createElement(t)
    v.onload = function () {
      window.cx_armin.init({
        widgetId: 'YOUR_WIDGET_ID',
        user: {
          email: 'alex@example.com',
          name: 'Alex Morgan',
          company: 'Example Shop',
        },
      })
    }
    v.src = 'https://cxwidget.chatarmin.com/index.js'
    d.body.appendChild(v)
  })(document, 'script')
</script>

If your website loads the visitor’s details asynchronously, wait for them before calling init(). Do not add a second installation snippet or rely on calling init() again to update the visitor after the widget has loaded.

Supported details and storage

All three properties are optional strings. They are sent with the visitor’s chat message, not saved just by loading or opening the widget.

Property	What happens on the contact
`user.email`	Fills the email only if the contact has no email.
`user.name`	Sets first and last name only if the contact has no first name. Leading and trailing whitespace is removed; the first word becomes the first name, and the remaining words become the last name. A single word leaves the last name empty.
`user.company`	Fills `company` in the contact’s metadata only if it is empty. Other metadata is preserved.

Chatarmin CX first looks for the contact associated with the widget’s browser session in your workspace. If none exists, it creates a contact or may reuse an existing contact with a matching email in that workspace. An email is not a verified identity. Existing non-empty email, first name, and company values are not overwritten. This is not a general contact-update API. The live widget supports only email, name, and company in user. You cannot set phone numbers, tags, or arbitrary custom contact fields this way. Use init({ widgetId, user }) for this integration, not a separate identify() call.

These values are unverified hints supplied by the browser. They do not authenticate the visitor or prove ownership of an email address. Never use them alone to authorize access to orders, accounts, or other private data. Do not put passwords, API keys, or other secrets in the snippet.

Test your setup

Use a test widget and a fresh browser session with synthetic contact details. Choose a valid test email that is not already on a contact in your test workspace. Load the page and send a chat message. Open the resulting ticket in Chatarmin CX and check its contact: the example should produce email alex@example.com, first name Alex, last name Morgan, and company Example Shop. Loading or opening the widget alone does not save these details. If an existing value stays unchanged, check whether that contact field was already filled. The widget tells your website what visitors do in the chat: opening it, sending a message, choosing a suggestion, clicking a link, leaving an email address and finishing a conversation. Use these events to see in Google Analytics 4 how the chat helps visitors convert. The events describe actions only. They never include message text, email addresses or phone numbers, and Chatarmin CX sends nothing to Google itself.

Send events to Google Tag Manager

Add analytics: { dataLayer: true } to your widget’s cx_armin.init() call. The widget then adds every event to your website’s window.dataLayer, named cx_armin_ plus the event name, for example cx_armin_message_sent. The event’s details are in cx_armin.

<script>
  ;(function (d, t) {
    var v = d.createElement(t)
    v.onload = function () {
      window.cx_armin.init({
        widgetId: 'YOUR_WIDGET_ID',
        analytics: { dataLayer: true },
      })
    }
    v.src = 'https://cxwidget.chatarmin.com/index.js'
    d.body.appendChild(v)
  })(document, 'script')
</script>

If your snippet already passes user or other options, add analytics to the same init() call. A sent message reaches the dataLayer like this:

{
  event: 'cx_armin_message_sent',
  cx_armin: { widgetId: 'YOUR_WIDGET_ID', ticketId: '7f3e…', source: 'typed', ts: 1792140000000 },
}

Before each event, the widget clears cx_armin, so a detail from an earlier event never carries over. In Preview mode, the clearing shows as a message without an event name. To send the events to Google Analytics 4, set up Google Tag Manager:

Create the variables

Go to Variables → User-Defined Variables → New → Data Layer Variable. Create one variable for each detail you want in Google Analytics, for example cx_armin.source, cx_armin.kind, cx_armin.url, cx_armin.type and cx_armin.reason.

Create the trigger

Go to Triggers → New → Custom Event. Enter cx_armin_.* as the event name and select Use regex matching.

Create the Google Analytics tag

Go to Tags → New → Google Analytics: GA4 Event. Enter your measurement ID, use the built-in Event variable as the event name, add your variables as event parameters and select the trigger from the previous step.

Test in Preview mode

Click Preview, open your website, open the chat and send a message. Tag Assistant shows cx_armin_open and cx_armin_message_sent with their details. Then publish the container.

Your Google Analytics tags follow your Google Tag Manager consent setup, like any other tag on your website.

Listen with JavaScript

Call window.cx_armin.on() with an event name and a function. The function receives the event’s details. Add your listeners right after init(), in the same onload function.

window.cx_armin.on('lead_submitted', function (event) {
  gtag('event', 'generate_lead', { method: event.type })
})

on() returns a function that stops listening. It only works for listeners added after the widget has loaded. Listeners that take no argument keep working. An error in your listener does not affect the chat; it still appears in your browser console. Every event includes widgetId and ts, the time in milliseconds. Conversation events also include ticketId once the conversation has a ticket in Chatarmin CX.

Event	When it fires	Details
`open`	The visitor opens the chat.
`close`	The visitor closes the chat.
`message_sent`	Chatarmin CX received a visitor message.	`source`: `typed`, `quick_reply` (a suggestion in the conversation) or `quick_pick` (a suggestion to start it)
`quick_reply_click`	The visitor chooses a suggestion.	`id`; `source`: `quick_reply` or `quick_pick`; `label` only for the start suggestions you set up
`cta_click`	The visitor clicks a link in a reply, a product card or a link suggestion.	`kind`: `link`, `product_card` or `button`; `url` only for a product card: the product page
`lead_submitted`	Chatarmin CX saves an email address on the visitor’s contact that they typed in the chat or entered in the email field the chat offers after a handoff to your team, or the visitor signs up in the back-in-stock form.	`type`: `email`; `source`: `chat`, `email_continuation` (the email field after a handoff) or `stock_request`
`conversation_completed`	The conversation is resolved or closed while the visitor is on your page, also when the visitor closes it. Choosing a suggestion such as That helped doesn’t count: it doesn’t resolve the conversation.	`reason`: `resolved` or `closed`
`handoff_requested`	The visitor chooses the suggestion to talk to a person.
`reply_received`	A reply from your AI agent or your team arrives while the visitor is on your page.	`sender`: `ai` or `human`
`rating`	The visitor rates a reply with a thumb.	`value`: `positive` or `negative`
`message`	A reply arrives and is unread. Kept for existing pages; use `reply_received` instead.

What the events leave out

A link in a reply or a link suggestion reports only its kind, no url: your team, your AI agent or you write these links, so any part of the address could be personal, such as a reset or invite link or a name in the domain. For a product card, url is the product page’s address without the query string and fragment. Parts of its path that could identify a person, such as an email address (even encoded several times), a long number or an access token, read :id, and so does any part of 16 or more characters that isn’t a slug of short words, such as a long single word like lagerraumvermietung.
label is sent only for the start suggestions you set up. Smart suggestions are generated for the visitor’s page, and a suggestion on a reply can be written by the AI. Either can repeat details from the page or the conversation, so they report only their id. A label that contains an @ or a long number is always left out.
lead_submitted says that an email address was given, never the address.

Good to know

Events fire only while the visitor is on your page. A conversation your team closes after the visitor left is not reported.
An email typed in the chat counts as a lead when it is the only address in the message and Chatarmin CX takes it for the contact: not for a message with several addresses (even if one of them is your support address) or a placeholder such as test@example.com, and not when the contact already had an email from elsewhere. Your own support address typed alone counts too, so the widget never reveals which addresses are yours; it isn’t saved on the contact.
Phone numbers typed into the chat are not detected, because they can’t be told apart reliably from order numbers or dates. type is always email for now.
These events are part of the current web widget. If none of them fire on your website, contact support to check which widget version your workspace uses.

Watch the walkthrough

Watch the web widget setup guide

Get started

Dashboard

Inbox

Rules

AI Agents

Channels

Integrations

Settings

Troubleshooting

What you can configure

Recommended setup

Identify visitors with website contact details

Supported details and storage

Test your setup

Track widget events in Google Analytics

Send events to Google Tag Manager

Listen with JavaScript

Widget events

What the events leave out

Good to know

Watch the walkthrough

​What you can configure

​Recommended setup

​Identify visitors with website contact details

​Supported details and storage

​Test your setup

​Track widget events in Google Analytics

​Send events to Google Tag Manager

​Listen with JavaScript

​Widget events

​What the events leave out

​Good to know

​Watch the walkthrough

What you can configure

Recommended setup

Identify visitors with website contact details

Supported details and storage

Test your setup

Track widget events in Google Analytics

Send events to Google Tag Manager

Listen with JavaScript

Widget events

What the events leave out

Good to know

Watch the walkthrough