Migrating from the Chat widget syntax
Migrating from the Chat widget syntax
This article describes how to migrate from the Chat widget syntax to the unified Web Widget (Classic) syntax.
The vast majority of the legacy $zopim.livechat APIs are aliased so they'll continue to work without the need to update any code.
In some cases, subtle differences might exist in how the APIs behave in the Web Widget (Classic) compared to the Chat widget. For example, the Web Widget doesn't have any separation between its launcher and window, so if you call hide or setOffset it is applied to the entire widget instead of just the launcher or window. Refer to the notes of each API below for more detail.
If you intend to continue using the $zopim.livechat syntax for some time before migrating to the new zE syntax, refer to Using the Chat widget JavaScript API in the Zendesk help center to understand how to correctly wrap $zopim.livechat API calls when using zE.
To read detailed descriptions for each API, refer to the Web Widget (Classic) developer documentation.
General APIs
| $zopim.livechat syntax | zE syntax |
|---|---|
| authenticate | zESettings.webWidget.authenticate.chat |
| badge.hide | zE('webWidget', 'hide') |
| badge.show | zE('webWidget', 'show') |
| button.hide | zE('webWidget', 'hide') |
| button.show | zE('webWidget', 'show') |
| endChat | zE('webWidget', 'chat:end') |
| hideAll | zE('webWidget', 'hide') |
| isChatting | zE('webWidget:get', 'chat:isChatting') |
| addTags | zE('webWidget', 'chat:addTags', array<string>) |
| removeTags | zE('webWidget', 'chat:removeTags', array<string>) |
| say | zE('webWidget', 'chat:send', msg) |
| set* | zE('webWidget', 'prefill', data<object>) and zE('webWidget', 'setLocale', data<string>) |
| setDefaultImplicitConsent | zESettings.cookies |
| setLanguage | zE('webWidget', 'setLocale', data<string>) |
| window.popout | zE('webWidget', 'popout') |
| window.toggle | zE('webWidget', 'toggle') |
| window.hide | zE('webWidget', 'hide') |
| window.show* | zE('webWidget', 'open') |
| window.getDisplay | zE('webWidget:get', 'display') |
* $zopim.livechat.set() currently supports the following APIs: name, email and language. * $zopim.livechat.window.show() will show the chat product in the widget by default.
Visitor Information
| $zopim.livechat syntax | zE syntax |
|---|---|
| setName* | zE('webWidget', 'prefill', { name: { value: 'John Doe', readOnly: true|false }}) |
| setEmail* | zE('webWidget', 'prefill', { email: { value: '[email protected]', readOnly: true|false }}) |
| setPhone* | zE('webWidget', 'prefill', { phone: { value: '12345678', readOnly: true|false }}) |
| sendVisitorPath | zE('webWidget', 'updatePath') |
| clearAll | zE('webWidget', 'logout') |
* You can set the name, phone, and email at the same time using the new prefill API. To set multiple attributes concurrently, provide a prefill object that has a key for each attribute. Example:
zE('webWidget', 'prefill', {name: { … },email: { … },phone: { … }})
Events
| $zopim.livechat syntax | zE syntax |
|---|---|
| setOnConnected | zE('webWidget:on', 'chat:connected', () => {}) |
| setOnChatStart | zE('webWidget:on', 'chat:start', () => {}) |
| setOnChatEnd | zE('webWidget:on', 'chat:end', () => {}) |
| setOnStatus | zE('webWidget:on', 'chat:status', (status) => {}) |
| setOnUnreadMsgs | zE('webWidget:on', 'chat:unreadMessages', (msgs) => {}) |
| window.onShow | zE('webWidget:on', 'open', () => {}) |
| window.onHide | zE('webWidget:on', 'close', () => {}) |
Customization APIs
| $zopim.livechat syntax | zE syntax |
|---|---|
| badge.setColor | zESettings.webWidget.color.launcher |
| badge.setLayout | zESettings.webWidget.launcher.badge.layout |
| badge.setImage | zESettings.webWidget.launcher.badge.image |
| badge.setText | zESettings.webWidget.launcher.badge.label |
| button.setOffsetVertical | zESettings.webWidget.offset.vertical |
| button.setOffsetVerticalMobile | zESettings.webWidget.offset.mobile.vertical |
| button.setOffsetHorizontal | zESettings.webWidget.offset.horizontal |
| button.setOffsetHorizontalMobile | zESettings.webWidget.offset.mobile.horizontal |
| button.setPosition* | zESettings.webWidget.position |
| button.setPositionMobile* | zESettings.webWidget.position |
| button.setColor | zESettings.webWidget.color.launcher |
| button.setOffsetBottom | zESettings.webWidget.offset.vertical |
| window.setColor | zESettings.webWidget.color.theme |
| window.setTitle | zESettings.webWidget.chat.title |
| window.setOffsetVertical | zESettings.webWidget.offset.vertical |
| window.setOffsetHorizontal | zESettings.webWidget.offset.horizontal |
| window.setOffsetBottom | zESettings.webWidget.offset.vertical |
| window.setPosition* | zESettings.webWidget.position |
| prechatForm.setGreetings | zESettings.webWidget.chat.prechatForm.greeting |
| offlineForm.setGreetings | zESettings.webWidget.chat.offlineForm.greeting |
| mobileNotifications.setDisabled | zESettings.webWidget.chat.notifications.mobile.disable |
| theme.setColor* | zESettings.webWidget.color.theme |
| theme.setColors* | zESettings.webWidget.color.theme |
| theme.setProfileCardConfig | zESettings.webWidget.chat.profileCard.avatar, zESettings.webWidget.chat.profileCard.title, zESettings.webWidget.chat.profileCard.rating |
| setDisableGoogleAnalytics | zESettings.analytics |
| setGreetings | zESettings.webWidget.launcher.chatLabel |
| setStatus | The $zopim.livechat syntax is supported. However, it is not mapped to the unified Web Widget API |
| button.setHideWhenOffline | zESettings.webWidget.chat.hideWhenOffline |
* All the position values supported in the legacy Chat Widget can be used except for tm (Top middle), and bm (Bottom middle). See the complete list of position values in the legacy Chat documentation. Also note that setting the position for mobile or desktop will affect both mobile and desktop versions of the web widget.
* $zopim.livechat.theme.setColor supports the primary color only.
* $zopim.livechat.theme.setColors supports the primary color only.
Concierge
| $zopim.livechat syntax | zE syntax |
|---|---|
| concierge.setAvatar | zESettings.webWidget.chat.concierge.avatarPath |
| concierge.setName | zESettings.webWidget.chat.concierge.name |
| concierge.setTitle | zESettings.webWidget.chat.concierge.title |
Departments
| $zopim.livechat syntax | zE syntax |
|---|---|
| departments.filter | zESettings.webWidget.chat.departments.enabled |
| departments.setVisitorDepartment | zESettings.webWidget.chat.departments.select |
| departments.clearVisitorDepartment | zESettings.webWidget.chat.departments.select |
| departments.getDepartment | zE('webWidget:get', 'chat:department', id or name) |
| departments.getAllDepartments | zE('webWidget:get', 'chat:departments') |
| departments.setLabel | zESettings.webWidget.chat.prechatForm.departmentLabel |
What APIs are not supported
Below is a list of the $zopim.livechat APIs that are not supported in the Web Widget (Classic). Due to low adoption of these APIs in the standalone Chat widget, they won't be migrated over to the new experience.
Deprecated
| $zopim.livechat syntax | Notes |
|---|---|
| setDisableSound | Admin setting has replaced the need for this |
| setNotes | No longer supported for security reasons |
| appendNotes | As above |
| bubble.show | Chat bubble feature is no longer supported |
| bubble.hide | As above |
| bubble.reset | As above |
| bubble.setTitle | As above |
| bubble.setText | As above |
| bubble.setColor | As above |
| getName | As above |
| getEmail | As above |
| getPhone | As above |
| setSize | As above |
| theme.reload | Theme API calls are applied automatically and do not require this subsequent call |
| theme.setFontConfig | Chat themes are no longer available |
| theme.setTheme | As above |
| cookieLaw.comply | Cookie law format is changing |