@livechat/customer-sdk 4.0.2 → 5.0.0

package/README.md

@@ -33,7 +33,7 @@ customerSDK.auth.getToken().then(token => {
 
 ## Questions
 
-If you have any questions, you can start a chat with our [24/7 Support](https://direct.lc.chat/1520/125).
+If you have any questions, you can start a chat with our [24/7 Support](https://direct.lc.chat/19196658/11).
 
 # How to start
 
@@ -93,6 +93,7 @@ Other optional configuration parameters are also available:
 | page.url             | string             |         | Optional; customer page url.                                                                                                                                                                                                                                        |
 | page.title           | string             |         | Optional; customer page title.                                                                                                                                                                                                                                      |
 | referrer             | string             |         | Optional; page referrer                                                                                                                                                                                                                                             |
+| tabId                | string             |         | Optional; an identifier for the browser tab. When provided, it is sent as `tab_id` in the login payload. Useful for distinguishing multiple tabs from the same customer.                                                                                            |
 
 CustomerData:
 
@@ -367,7 +368,7 @@ Starts the connection process to our servers. It is needed when:
 
 ```js
 const customerSDK = CustomerSDK.init({
-  licenseId: LICENSE_ID,
+  organizationId: ORGANIZATION_ID,
   clientId: CLIENT_ID,
   autoConnect: false,
 })
@@ -681,44 +682,6 @@ Returned value:
 | form.id     | string   |                                             |
 | form.fields | object[] |                                             |
 
-## getPredictedAgent
-
-```js
-customerSDK
-  .getPredictedAgent({
-    groupId: 0,
-  })
-  .then(agent => {
-    console.log(agent)
-  })
-  .catch(error => {
-    console.log(error)
-  })
-```
-
-Parameters:
-
-| parameters | type   | description |
-| ---------- | ------ | ----------- |
-| groupId    | number | Optional    |
-
-Returned value:
-
-| properties     | type    | description                                                   |
-| -------------- | ------- | ------------------------------------------------------------- |
-| agent          | object  |                                                               |
-| agent.id       | string  |                                                               |
-| agent.name     | string  |                                                               |
-| agent.jobTitle | string  |                                                               |
-| agent.type     | 'agent' |                                                               |
-| agent.isBot    | boolean |                                                               |
-| queue          | boolean | True when the current group has reached concurrent chat limit |
-
-### Errors
-
-- `GROUP_OFFLINE` - the requested group is offline, and it was not possible to return a predicted Agent for it.
-- `GROUP_UNAVAILABLE` - thrown when manual routing is enabled for the group and a predicted Agent is requested for it. If you call `startChat` or `resumeChat` accordingly, you'll end up in the queue.
-
 ## getUrlInfo
 
 It returns the info on a given URL.
@@ -970,6 +933,49 @@ Returned value:
 
 - `MISSING_CHAT_THREAD` - the targeted chat cannot be rated because it has no threads.
 
+## requestWelcomeMessage
+
+Requests a welcome message for the current customer. The welcome message is returned via the [`incoming_welcome_message`](#incoming_welcome_message) event.
+
+```js
+customerSDK
+  .requestWelcomeMessage({
+    id: 'previous-welcome-message-id',
+  })
+  .then(response => {
+    console.log(response)
+  })
+  .catch(error => {
+    console.log(error)
+  })
+```
+
+Parameters:
+
+| parameters | type   | description                                           |
+| ---------- | ------ | ----------------------------------------------------- |
+| id         | string | Optional; ID of a previously received welcome message |
+
+Returned value:
+
+| properties              | type    | description                                                   |
+| ----------------------- | ------- | ------------------------------------------------------------- |
+| id                      | string  | Welcome message ID                                            |
+| predictedAgent          | object  | Predicted agent object                                        |
+| predictedAgent.id       | string  | Predicted agent ID                                            |
+| predictedAgent.avatar   | string  | Predicted agent avatar URL                                    |
+| predictedAgent.name     | string  | Predicted agent name                                          |
+| predictedAgent.jobTitle | string  | Predicted agent job title                                     |
+| predictedAgent.type     | string  | Predicted agent type                                          |
+| predictedAgent.botType  | string  | Predicted agent bot type: 'chatbot' or 'ai_agent'             |
+| predictedAgent.isBot    | boolean | Predicted agent is bot flag                                   |
+| queue                   | boolean | True when the current group has reached concurrent chat limit |
+
+### Errors
+
+- `GROUP_OFFLINE` - the requested group is offline, and it was not possible to return a predicted Agent for it.
+- `GROUP_UNAVAILABLE` - thrown when manual routing is enabled for the group and a predicted Agent is requested for it. If you call `startChat` or `resumeChat` accordingly, you'll end up in the queue.
+
 ## resumeChat
 
 Resumes an archived chat.
@@ -998,6 +1004,7 @@ Parameters:
 | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
 | data.active                 | boolean | Optional; defaults to `true` but can be used to create threads that are immediately inactive                      |
 | data.continuous             | boolean | Optional                                                                                                          |
+| data.welcomeMessageId       | string  | Optional; ID of a previously received welcome message                                                             |
 | data.chat.id                | string  |                                                                                                                   |
 | data.chat.access            | Access  | Optional                                                                                                          |
 | data.chat.properties        | object  | Optional, [Default properties docs](https://developers.livechat.com/docs/messaging/references/default-properties) |
@@ -1075,6 +1082,31 @@ Parameters:
 | postback.id      | string  |         | Postback button ID |
 | postback.toggled | boolean | true    | Postback toggled   |
 
+## sendGreetingButtonClicked
+
+Sends information to the server about a Customer's interaction with a greeting button. This is used for tracking button clicks in greetings that have a `buttonId` property.
+
+```js
+customerSDK
+  .sendGreetingButtonClicked({
+    greetingUniqueId: 'Q10X0W041P',
+    buttonId: '20ff0b3f-fbed-49f4-b13f-788c9ec66f03',
+  })
+  .then(() => {
+    console.log('success')
+  })
+  .catch(error => {
+    console.log(error)
+  })
+```
+
+Parameters:
+
+| parameters       | type   | description                                               |
+| ---------------- | ------ | --------------------------------------------------------- |
+| greetingUniqueId | string | Unique ID of the greeting received in `incoming_greeting` |
+| buttonId         | string | ID of the clicked button                                  |
+
 ## setCustomerSessionFields
 
 Sends the request to set customer's session fields. They are available for the duration of the session.
@@ -1141,6 +1173,7 @@ Parameters:
 | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
 | active                 | boolean | Optional, defaults to `true` but can be used to create threads that are immediately inactive                      |
 | continuous             | boolean | Optional                                                                                                          |
+| welcomeMessageId       | string  | Optional; ID of a previously received welcome message                                                             |
 | chat.access            | access  | Optional                                                                                                          |
 | chat.properties        | object  | Optional, [Default properties docs](https://developers.livechat.com/docs/messaging/references/default-properties) |
 | chat.thread.events     | event[] | Optional; initial events that will immediately become a part of the created thread.                               |
@@ -1524,24 +1557,27 @@ Payload:
 | -------- | ------ |
 | id       | string |
 
-## Customer page updated
+## Customer identity changed
 
-The Customer moved to another page, for example by following a link on your website.
+Informs that the customer identity has changed, typically due to browser privacy features blocking authentication cookies. The SDK handles this gracefully by clearing sensitive session data and switching to the new identity without crashing.
 
 ```js
-customerSDK.on('customer_page_updated', payload => {
-  const { url, title, openedAt } = payload
-  console.log('customer_page_updated', { url, title, openedAt })
+customerSDK.on('identity_changed', ({ previousId, newId }) => {
+  console.log('Customer identity changed', {
+    from: previousId,
+    to: newId,
+  })
+  // Clear any application-specific cached data
+  // tied to the previous customer identity
 })
 ```
 
 Payload:
 
-| properties | type   |                                                      |
-| ---------- | ------ | ---------------------------------------------------- |
-| url        | string | URL of the Customer current website                  |
-| title      | string | Title of the Customer current website                |
-| openedAt   | string | Date of the last update in RFC 3339 date-time format |
+| properties | type   | description              |
+| ---------- | ------ | ------------------------ |
+| previousId | string | The previous customer ID |
+| newId      | string | The new customer ID      |
 
 ## Customer updated
 
@@ -1841,6 +1877,88 @@ Payload:
 | typingIndicator.authorId | string  | User ID     |
 | typingIndicator.isTyping | boolean |             |
 
+## Incoming thinking indicator
+
+Informs that an AI agent is currently thinking or processing a request.
+The push payload contains information about the thinking state including optional custom title and description.
+
+```js
+customerSDK.on('incoming_thinking_indicator', payload => {
+  console.log(`Agent ${payload.authorId} is thinking in chat ${payload.chatId}`)
+
+  if (payload.title) {
+    console.log(`Thinking title: ${payload.title}`)
+  }
+
+  if (payload.description) {
+    console.log(`Thinking description: ${payload.description}`)
+  }
+
+  if (payload.customId) {
+    console.log(`Custom ID: ${payload.customId}`)
+  }
+})
+```
+
+Payload:
+
+| properties  | type   | description                                                 |
+| ----------- | ------ | ----------------------------------------------------------- |
+| chatId      | string | Chat ID                                                     |
+| threadId    | string | Thread ID                                                   |
+| authorId    | string | Agent ID who is thinking                                    |
+| sentAt      | string | ISO timestamp when the thinking indicator was sent          |
+| customId    | string | Optional. Custom identifier for dismissing this indicator   |
+| title       | string | Optional. Custom thinking title (defaults to "Thinking...") |
+| description | string | Optional. Additional description text                       |
+
+## Incoming welcome message
+
+Informs about a welcome message received in response to [`requestWelcomeMessage`](#requestwelcomemessage).
+If you want to include the welcome message in the chat, you can use the `welcome_message_id` parameter in the [`resumeChat`](#resumechat) or [`startChat`](#startchat) method.
+
+```js
+customerSDK.on('incoming_welcome_message', payload => {
+  const { id, event } = payload
+  console.log('incoming_welcome_message', { id, event })
+})
+```
+
+Payload:
+
+| properties | type   | description                   |
+| ---------- | ------ | ----------------------------- |
+| id         | string | Welcome message ID            |
+| event      | object | Message or rich message event |
+
+## Incoming event preview
+
+Informs about an event preview before it's officially sent to the chat.
+This allows clients to display a preview of the event content.
+Only text events are supported for preview.
+
+```js
+customerSDK.on('incoming_event_preview', payload => {
+  console.log(
+    `Event preview in chat ${payload.chatId}, thread ${payload.threadId}`,
+  )
+
+  if (payload.event && payload.event.type === 'message') {
+    console.log(`Preview text: ${payload.event.text}`)
+  }
+})
+```
+
+Payload:
+
+| properties | type   | description                                   |
+| ---------- | ------ | --------------------------------------------- |
+| chatId     | string | Chat ID                                       |
+| threadId   | string | Thread ID                                     |
+| event      | object | Event object (only text events are supported) |
+| event.type | string | Event type                                    |
+| event.text | string | Event text content (for message type events)  |
+
 ## Queue position updated
 
 Informs that the queue position has been updated.
@@ -1958,17 +2076,18 @@ Informs that a user was removed from a chat.
 
 ```js
 customerSDK.on('user_removed_from_chat', payload => {
-  const { chatId, userId } = payload
-  console.log('user_removed_from_chat', { chatId, userId })
+  const { chatId, userId, reason } = payload
+  console.log('user_removed_from_chat', { chatId, userId, reason })
 })
 ```
 
 Payload:
 
-| properties | type   | description |
-| ---------- | ------ | ----------- |
-| chatId     | string | Chat ID     |
-| userId     | string | User ID     |
+| properties | type   | description                                                                                                                                            |
+| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| chatId     | string | Chat ID                                                                                                                                                |
+| userId     | string | User ID                                                                                                                                                |
+| reason     | string | Reason why user was removed, one of: 'disconnected', 'signed_out', 'remotely_signed_out', 'deleted', 'chat_deactivated', 'manual', 'inactive', 'other' |
 
 # Disconnection reasons
 
@@ -2008,9 +2127,12 @@ This internally destroys the current instance of Customer SDK, so it won't be po
 
 ## Identity mismatch
 
-The identity of the Customer has changed between reconnects. This might happen if cookies can't be persisted in the browser.
+Customer SDK handles identity changes gracefully by:
 
-This internally destroys the current instance of Customer SDK, so it won't be possible to reuse it.
+- Automatically switching to the new customer identity
+- Clearing sensitive session data (chats, cached user data) for security
+- Maintaining SDK functionality without crashes
+- Emitting an `identity_changed` event for developer awareness
 
 ## Inactivity timeout
 
@@ -2134,6 +2256,30 @@ customerSDK.on('disconnected', ({ reason }) => {
 
 # Changelog
 
+## [v5.0.0] - 2026-05-12
+
+### Added
+
+- New `reason` field to `user_removed_from_chat` event, indicating why the user was removed.
+- New `sendGreetingButtonClicked` method for tracking greeting button clicks.
+- New `requestWelcomeMessage` method for requesting welcome messages.
+- Support for `incoming_thinking_indicator` push event.
+- Support for `incoming_event_preview` push event.
+- Support for `incoming_welcome_message` push event.
+- Support for `identity_changed` event.
+- Support for `ecommerce` template in rich messages.
+- Optional `formType` field on parsed `form` and `filled_form` events, representing the custom form type assigned by the server.
+- Support for optional `tabId` configuration parameter, sent as `tab_id` in the login payload.
+
+### Changed
+
+- Switched to using Customer API 3.6.
+
+### Removed
+
+- Support for `customer_page_updated` push.
+- Support for `get_predicted_agent` request.
+
 ## [v4.0.2] - 2023-11-02
 
 ### Added