Skip to main content
Version 2 of the Chat Widget is a new rendering engine with the same JavaScript API. Your existing integration code keeps working — what changes is the markup the widget produces, and which features a variant starts with.
Nothing happens until you choose it. @latest and a bare package name still install v1, so an embed you do not touch keeps running v1 exactly as it does today.

​
1. Point the script tag at v2

That is the only required change for most integrations. Every method and configuration field keeps its name, and two behaviours changed — see what stays the same.
Using the WordPress plugin? Skip this step — the plugin loads its own copy of the widget and updates on its own schedule. Steps 2 and 3 still apply to you.

​
2. Create a new variant for the features v2 adds

Variants created before v2 carry no setting for the five features v2 added. Rather than guess, the widget leaves them off, so upgrading never switches something on in your chat that you did not choose. That means an existing variant renders v2 without:
  • Pinned messages
  • Saved messages
  • Pinned conversations
  • Thread subscription
  • Multiple attachments
To get them, create a new variant in the Widget Builder — new variants start with the full v2 feature set. An existing variant cannot be switched over, so the builder does not offer these five settings on one. Everything else your variant configures — layout, colours, fonts, tabs, the docked button — carries over untouched, and every feature your variant already had keeps working.

​
3. Check your custom CSS and JavaScript

This is the part most likely to need work, and the only one that can change how your widget looks without any error appearing. v2 renames most CSS classes. If you added Custom CSS in the Widget Builder’s Custom Code panel, rules written against v1 class names will no longer match, and those styles will silently stop applying. Check your rules against the class names in the UI Kit documentation, which is what v2 renders. Custom JavaScript fails more loudly. Code that looked elements up by a v1 class name now gets null back, so a script that worked before may throw instead of quietly doing nothing. Check any querySelector or getElementsByClassName call that targets a CometChat element. CSS variables changed too — some --cometchat-* names from v1 no longer exist. Any rule that sets one that was removed has no effect.

​
4. What does not change

The entire JavaScript API, verified call by call: CometChatAuth.start · init · login · logout · launch · chatWithUser · chatWithGroup · callUser · callGroup · uiEvent · localize · createOrUpdateUser · createOrUpdateGroup · showDockedUnreadCount · showGroupActionMessages Every configuration field keeps its name, and the embed snippet has the same shape. Two behaviours did change — check these if your integration relies on either: Otherwise, if your integration only calls the API and passes configuration, step 1 is the whole upgrade.

​
5. Going back to v1

Pin the last v1 build:
Your variant is unaffected by the version you load, so switching back needs no other change.

​
Checklist

1

Update the script tag

@1.x.x → @2.x.x, unless you use the WordPress plugin.
2

Create a new variant

Only if you want the five features v2 adds.
3

Re-check custom CSS

Rules written against v1 class names will not match.
4

Re-check custom JavaScript

Selectors that targeted v1 class names now return null.