@hellotext/hellotext 2.3.9 → 2.4.0

package/src/controllers/webchat_controller.js

@@ -6,10 +6,12 @@ import WebchatChannel from '../channels/webchat_channel'
 import Hellotext from '../hellotext'
 
 import { Locale } from '../core'
-import { Webchat as WebchatConfiguration, behaviors } from '../core/configuration/webchat'
+import { Webchat as WebchatConfiguration, modes } from '../core/configuration/webchat'
 
-import { LogoBuilder } from '../builders/logo_builder'
 import { usePopover } from './mixins/usePopover'
+import { useBehaviour } from './webchat/useBehaviour'
+import { useOpeningSequence } from './webchat/useOpeningSequence'
+import { useTeaser } from './webchat/useTeaser'
 
 export default class extends Controller {
   static values = {
@@ -26,7 +28,10 @@ export default class extends Controller {
     typingIndicatorKeepAlive: { type: Number, default: 30000 }, // 30 seconds
     offset: { type: Number, default: 24 },
     padding: { type: Number, default: 24 },
-    optimisticTypingIndicatorWait: { type: Number, default: 1000 }, // 1 second
+    optimisticTypingIndicatorWait: { type: Number, default: 1000 }, // 1 second,
+    teaser: Object,
+    messageTeaser: String,
+    behaviour: Object,
   }
 
   static classes = ['fadeOut']
@@ -51,6 +56,9 @@ export default class extends Controller {
     'unreadCounter',
     'typingIndicator',
     'typingIndicatorTemplate',
+    'teaser',
+    'openingSequence',
+    'openingSequenceMessage',
   ]
 
   initialize() {
@@ -63,6 +71,7 @@ export default class extends Controller {
     )
 
     this.files = []
+    this.messageIds = new Set()
 
     this.onMessageReceived = this.onMessageReceived.bind(this)
     this.onMessageReaction = this.onMessageReaction.bind(this)
@@ -77,13 +86,24 @@ export default class extends Controller {
   }
 
   connect() {
+    useBehaviour(this)
     usePopover(this)
-
-    this.popoverTarget.classList.add(...WebchatConfiguration.classes)
-    this.triggerTarget.classList.add(...WebchatConfiguration.triggerClasses)
+    useOpeningSequence(this)
+    useTeaser(this)
 
     this.setupFloatingUI({ trigger: this.triggerTarget, popover: this.popoverTarget })
 
+    if (this.hasTeaserTarget) {
+      this.setupFloatingUI({
+        trigger: this.triggerTarget,
+        popover: this.teaserTarget,
+        strategy: 'absolute',
+      })
+    }
+
+    this.setupTeaser()
+    this.setupOpeningSequence()
+
     this.webChatChannel.onMessage(this.onMessageReceived)
     this.webChatChannel.onTypingStart(this.onTypingStart)
 
@@ -91,21 +111,22 @@ export default class extends Controller {
 
     this.messagesContainerTarget.addEventListener('scroll', this.onScroll)
 
-    if (!Hellotext.business.features.white_label) {
-      this.toolbarTarget.appendChild(LogoBuilder.build())
-    }
-
     if (this.shouldOpenOnMount) {
       this.openValue = true
     }
 
     Hellotext.eventEmitter.dispatch('webchat:mounted')
     this.broadcastChannel.addEventListener('message', this.onOutboundMessageSent)
+    this.scheduleBehaviourOpen()
 
     super.connect()
   }
 
   disconnect() {
+    this.cancelBehaviourOpen()
+    this.teardownTeaser()
+    this.teardownOpeningSequence()
+
     this.broadcastChannel.removeEventListener('message', this.onOutboundMessageSent)
     this.messagesContainerTarget.removeEventListener('scroll', this.onScroll)
 
@@ -273,7 +294,7 @@ export default class extends Controller {
           image.src = attachmentUrl
           image.style.display = 'block'
 
-          element.querySelector('[data-attachment-container]').appendChild(image)
+          this.messageAttachmentsContainer(element)?.appendChild(image)
         })
       }
 
@@ -291,7 +312,7 @@ export default class extends Controller {
 
   onClickOutside(event) {
     if (
-      WebchatConfiguration.behaviour === behaviors.POPOVER &&
+      WebchatConfiguration.mode === modes.POPOVER &&
       this.openValue &&
       event.target.nodeType &&
       this.element.contains(event.target) === false
@@ -310,6 +331,7 @@ export default class extends Controller {
 
   onPopoverOpened() {
     this.popoverTarget.classList.remove(...this.fadeOutClasses)
+    this.dismissTeaserForSession?.()
 
     if (!this.onMobile) {
       this.inputTarget.focus()
@@ -329,6 +351,12 @@ export default class extends Controller {
     Hellotext.eventEmitter.dispatch('webchat:opened')
     localStorage.setItem(`hellotext--webchat--${this.idValue}`, 'opened')
 
+    if (this.messageTeaserValue) {
+      this.messageTeaserValue = null
+    }
+
+    this.startOpeningSequence()
+
     if (this.unreadCounterTarget.style.display === 'none') return
 
     this.unreadCounterTarget.style.display = 'none'
@@ -367,7 +395,11 @@ export default class extends Controller {
   }
 
   onMessageReceived(message) {
-    const { id, body, attachments } = message
+    const { id, body, attachments, teaser } = message
+
+    if (!this.claimMessageId(id)) return
+
+    this.hideTeaser?.()
 
     if (message.carousel) {
       return this.insertCarouselMessage(message)
@@ -380,6 +412,8 @@ export default class extends Controller {
     element.style.display = 'flex'
 
     element.querySelector('[data-body]').innerHTML = div.innerHTML
+
+    element.setAttribute('data-id', id)
     element.setAttribute('data-hellotext--webchat-target', 'message')
 
     if (attachments) {
@@ -388,7 +422,7 @@ export default class extends Controller {
         image.src = attachmentUrl
         image.style.display = 'block'
 
-        element.querySelector('[data-attachment-container]').appendChild(image)
+        this.messageAttachmentsContainer(element)?.appendChild(image)
       })
     }
 
@@ -402,21 +436,45 @@ export default class extends Controller {
 
     element.scrollIntoView({ behavior: 'smooth' })
 
+    this.updateMessageTeaser(teaser)
+
     if (this.openValue) {
       this.messagesAPI.markAsSeen(id)
       return
     }
 
-    this.unreadCounterTarget.style.display = 'flex'
+    this.incrementUnreadCounter()
+  }
 
-    const unreadCount = (parseInt(this.unreadCounterTarget.innerText) || 0) + 1
-    this.unreadCounterTarget.innerText = unreadCount > 99 ? '99+' : unreadCount
+  // TCP broadcasts may deliver the same incoming message twice before Stimulus
+  // has connected the appended message target. Claiming the id in memory closes
+  // that window, while the target check still drops messages rendered earlier.
+  claimMessageId(id) {
+    const messageTargets = this.messageTargets || []
+
+    if (this.messageIds.has(id)) return false
+
+    this.messageIds.add(id)
+
+    return !messageTargets.some(element => element.dataset.id === id)
+  }
+
+  updateMessageTeaser(teaser) {
+    this.messageTeaserValue = teaser
+
+    if (this.messageTeaserValue && this.hasTeaserTarget) {
+      this.teaserTarget.innerHTML = this.messageTeaserValue
+      this.teaserTarget.classList.toggle('invisible', this.openValue)
+    }
   }
 
   insertCarouselMessage(message) {
     const html = message.html
     const element = new DOMParser().parseFromString(html, 'text/html').body.firstElementChild
 
+    element.setAttribute('data-id', message.id)
+    element.setAttribute('data-hellotext--webchat-target', 'message')
+
     this.clearTypingIndicator()
     this.messagesContainerTarget.appendChild(element)
 
@@ -427,14 +485,14 @@ export default class extends Controller {
       body: element.querySelector('[data-body]')?.innerText || '',
     })
 
+    this.updateMessageTeaser(message.teaser)
+
     if (this.openValue) {
       this.messagesAPI.markAsSeen(message.id)
       return
     }
 
-    this.unreadCounterTarget.style.display = 'flex'
-    const unreadCount = (parseInt(this.unreadCounterTarget.innerText) || 0) + 1
-    this.unreadCounterTarget.innerText = unreadCount > 99 ? '99+' : unreadCount
+    this.incrementUnreadCounter()
   }
 
   resizeInput() {
@@ -451,6 +509,8 @@ export default class extends Controller {
   }
 
   async sendQuickReplyMessage({ detail: { id, product, buttonId, body, cardElement } }) {
+    this.dismissTeaserForSession?.()
+
     const formData = new FormData()
 
     formData.append('message[body]', body)
@@ -460,6 +520,7 @@ export default class extends Controller {
 
     formData.append('session', Hellotext.session)
     formData.append('locale', Locale.toString())
+    this.appendOpeningSequenceMessageIds(formData)
 
     const element = this.buildMessageElement()
     const attachment = cardElement.querySelector('img')?.cloneNode(true)
@@ -470,7 +531,7 @@ export default class extends Controller {
       attachment.removeAttribute('width')
       attachment.removeAttribute('height')
 
-      element.querySelector('[data-attachment-container]').appendChild(attachment)
+      this.messageAttachmentsContainer(element)?.appendChild(attachment)
     }
 
     if (this.typingIndicatorVisible && this.hasTypingIndicatorTarget) {
@@ -503,6 +564,7 @@ export default class extends Controller {
     const data = await response.json()
 
     this.dispatch('set:id', { target: element, detail: data.id })
+    this.clearRevealedOpeningSequenceMessageIds()
 
     const message = {
       id: data.id,
@@ -517,9 +579,94 @@ export default class extends Controller {
     Hellotext.eventEmitter.dispatch('webchat:message:sent', message)
   }
 
-  async sendMessage(e) {
+  async sendTeaserQuickReply(event) {
+    event.preventDefault()
+    event.stopPropagation()
+
+    const button = event.currentTarget
+    const value = (button.dataset.value || '').trim()
+    const label = [button.dataset.text, button.textContent]
+      .map(text => (text || '').trim())
+      .find(text => text.length > 0)
+    const text = value || label
+
+    if (!text) return
+
+    this.dismissTeaserForSession?.()
+    this.show()
+
+    const buttonType = (button.dataset.type || '').trim() || 'quick_reply'
     const formData = new FormData()
 
+    formData.append('message[body]', text)
+    formData.append('session', Hellotext.session)
+    formData.append('locale', Locale.toString())
+    this.appendOpeningSequenceMessageIds(formData)
+
+    const element = this.buildMessageElement()
+
+    element.querySelector('[data-body]').innerText = text
+
+    if (this.typingIndicatorVisible && this.hasTypingIndicatorTarget) {
+      this.messagesContainerTarget.insertBefore(element, this.typingIndicatorTarget)
+    } else {
+      this.messagesContainerTarget.appendChild(element)
+    }
+
+    element.scrollIntoView({ behavior: 'smooth' })
+
+    this.broadcastChannel.postMessage({
+      type: 'message:sent',
+      element: element.outerHTML,
+    })
+
+    if (!this.typingIndicatorVisible) {
+      clearTimeout(this.optimisticTypingTimeout)
+      this.optimisticTypingTimeout = setTimeout(() => {
+        this.showOptimisticTypingIndicator()
+      }, this.optimisticTypingIndicatorWaitValue)
+    }
+
+    const response = await this.messagesAPI.create(formData)
+
+    if (response.failed) {
+      clearTimeout(this.optimisticTypingTimeout)
+
+      this.broadcastChannel.postMessage({
+        type: 'message:failed',
+        id: element.id,
+      })
+
+      return element.classList.add('failed')
+    }
+
+    const data = await response.json()
+    element.setAttribute('data-id', data.id)
+    this.clearRevealedOpeningSequenceMessageIds()
+
+    Hellotext.eventEmitter.dispatch('webchat:message:sent', {
+      id: data.id,
+      body: text,
+      attachments: [],
+      type: 'quick_reply',
+      teaser: {
+        text: label || text,
+        value: value || text,
+        type: buttonType,
+      },
+    })
+
+    if (data.conversation && data.conversation !== this.conversationIdValue) {
+      this.conversationIdValue = data.conversation
+      this.webChatChannel.updateSubscriptionWith(this.conversationIdValue)
+    }
+
+    if (this.typingIndicatorVisible) {
+      this.resetTypingIndicatorTimer()
+    }
+  }
+
+  async sendMessage(e) {
     const message = {
       body: this.inputTarget.value,
       attachments: this.files,
@@ -533,6 +680,10 @@ export default class extends Controller {
       return
     }
 
+    this.dismissTeaserForSession?.()
+
+    const formData = new FormData()
+
     if (this.inputTarget.value.trim().length > 0) {
       formData.append('message[body]', this.inputTarget.value)
     } else {
@@ -545,6 +696,7 @@ export default class extends Controller {
 
     formData.append('session', Hellotext.session)
     formData.append('locale', Locale.toString())
+    this.appendOpeningSequenceMessageIds(formData)
 
     const element = this.buildMessageElement()
 
@@ -558,7 +710,7 @@ export default class extends Controller {
 
     if (attachments.length > 0) {
       attachments.forEach(attachment => {
-        element.querySelector('[data-attachment-container]').appendChild(attachment.cloneNode(true))
+        this.messageAttachmentsContainer(element)?.appendChild(attachment.cloneNode(true))
       })
     }
 
@@ -614,6 +766,7 @@ export default class extends Controller {
     const data = await response.json()
     element.setAttribute('data-id', data.id)
     message.id = data.id
+    this.clearRevealedOpeningSequenceMessageIds()
 
     Hellotext.eventEmitter.dispatch('webchat:message:sent', message)
 
@@ -644,6 +797,17 @@ export default class extends Controller {
     return element
   }
 
+  messageAttachmentsContainer(element) {
+    return element.querySelector('[data-attachments-container], [data-attachment-container]')
+  }
+
+  incrementUnreadCounter() {
+    this.unreadCounterTarget.style.display = 'flex'
+
+    const unreadCount = (parseInt(this.unreadCounterTarget.innerText) || 0) + 1
+    this.unreadCounterTarget.innerText = Math.min(unreadCount, 9)
+  }
+
   openAttachment() {
     this.attachmentInputTarget.click()
   }

package/src/core/configuration/webchat.js

@@ -28,13 +28,13 @@ const strategies = {
 }
 
 /**
- * @typedef {'modal' | 'popover'} Behaviour
+ * @typedef {'modal' | 'popover'} Mode
  */
 
 /**
- * @enum {Behaviour}
+ * @enum {Mode}
  */
-const behaviors = {
+const modes = {
   MODAL: 'modal',
   POPOVER: 'popover',
 }
@@ -46,6 +46,20 @@ const behaviors = {
  * @property {string} typography - The typography style (e.g., font family).
  */
 
+/**
+ * @typedef {Object} Appearance
+ * @property {Object} [header] - Header appearance overrides.
+ * @property {string} [header.name] - Business name shown in the webchat header.
+ * @property {Object} [launcher] - Launcher appearance overrides.
+ * @property {string} [launcher.iconUrl] - Image URL used for the launcher icon.
+ */
+
+/**
+ * @typedef {Object} WhatsApp
+ * @property {string} [number] - WhatsApp number used by the handoff configuration.
+ * @property {boolean} [restrictToChannel] - Whether handoff should be restricted to the configured channel.
+ */
+
 /**
  * @class Webchat
  * @classdesc
@@ -53,10 +67,11 @@ const behaviors = {
  * @property {String} id - the id of the webchat.
  * @property {String} container - the container to append the webchat to, defaults to 'body'
  * @property {Placement} placement - the placement of the webchat within the container, defaults to "bottom-right".
- * @property {String} classes - additional classes to apply to the webchat popup.
- * @property {String} triggerClasses - additional classes to apply to the webchat popup trigger.
- * @property {Behaviour} behaviour - the behaviour of the webchat, defaults to 'popover'.
+ * @property {Mode} mode - how the webchat behaves while open, defaults to 'popover'.
+ * @property {Object} behaviour - runtime opening behaviour for the webchat.
  * @property {Style} style - the style of the webchat.
+ * @property {Appearance} appearance - appearance overrides.
+ * @property {WhatsApp} whatsapp - WhatsApp handoff overrides.
  * @property {Strategy} strategy - the strategy used to position the webchat. Defaults to 'absolute'
  */
 
@@ -64,10 +79,12 @@ class Webchat {
   static _id
   static _container = 'body'
   static _placement = 'bottom-right'
-  static _classes = []
-  static _triggerClasses = []
   static _style = {}
-  static _behaviour = behaviors.POPOVER
+  static _appearance = {}
+  static _whatsapp = {}
+  static _mode = modes.POPOVER
+  static _behaviour = null
+  static _hasBehaviourOverride = false
   static _strategy = null
 
   static set container(value) {
@@ -90,38 +107,6 @@ class Webchat {
     return this._placement
   }
 
-  static set classes(value) {
-    if (!Array.isArray(value) && typeof value !== 'string') {
-      throw new Error('classes must be an array or a string')
-    }
-
-    this._classes = value
-  }
-
-  static get classes() {
-    if (typeof this._classes === 'string') {
-      return this._classes.split(',').map(c => c.trim())
-    } else {
-      return this._classes
-    }
-  }
-
-  static set triggerClasses(value) {
-    if (!Array.isArray(value) && typeof value !== 'string') {
-      throw new Error('triggerClasses must be an array or a string')
-    }
-
-    this._triggerClasses = value
-  }
-
-  static get triggerClasses() {
-    if (typeof this._triggerClasses === 'string') {
-      return this._triggerClasses.split(',').map(c => c.trim())
-    } else {
-      return this._triggerClasses
-    }
-  }
-
   static set id(value) {
     this._id = value
   }
@@ -160,18 +145,113 @@ class Webchat {
     this._style = value
   }
 
+  static get appearance() {
+    return this._appearance
+  }
+
+  static set appearance(value) {
+    if (!this.isPlainObject(value)) {
+      throw new Error('Appearance must be an object')
+    }
+
+    Object.entries(value).forEach(([key, nestedValue]) => {
+      if (!['header', 'launcher'].includes(key)) {
+        throw new Error(`Invalid appearance property: ${key}`)
+      }
+
+      if (!this.isPlainObject(nestedValue)) {
+        throw new Error(`Appearance ${key} must be an object`)
+      }
+
+      Object.entries(nestedValue).forEach(([nestedKey, propertyValue]) => {
+        if (key === 'header' && nestedKey !== 'name') {
+          throw new Error(`Invalid appearance header property: ${nestedKey}`)
+        }
+
+        if (key === 'launcher' && nestedKey !== 'iconUrl') {
+          throw new Error(`Invalid appearance launcher property: ${nestedKey}`)
+        }
+
+        if (propertyValue == null) {
+          return
+        }
+
+        if (typeof propertyValue !== 'string') {
+          throw new Error(`Invalid appearance ${key}.${nestedKey} value: ${propertyValue}`)
+        }
+      })
+    })
+
+    this._appearance = value
+  }
+
+  static get whatsapp() {
+    return this._whatsapp
+  }
+
+  static set whatsapp(value) {
+    if (!this.isPlainObject(value)) {
+      throw new Error('WhatsApp must be an object')
+    }
+
+    Object.entries(value).forEach(([key, nestedValue]) => {
+      if (!['number', 'restrictToChannel'].includes(key)) {
+        throw new Error(`Invalid WhatsApp property: ${key}`)
+      }
+
+      if (nestedValue == null) {
+        return
+      }
+
+      if (key === 'number' && typeof nestedValue !== 'string') {
+        throw new Error(`Invalid WhatsApp number value: ${nestedValue}`)
+      }
+
+      if (key === 'restrictToChannel' && typeof nestedValue !== 'boolean') {
+        throw new Error(`Invalid WhatsApp restrictToChannel value: ${nestedValue}`)
+      }
+    })
+
+    this._whatsapp = value
+  }
+
+  static get mode() {
+    return this._mode
+  }
+
+  static set mode(value) {
+    if (!Object.values(modes).includes(value)) {
+      throw new Error(`Invalid mode value: ${value}`)
+    }
+
+    this._mode = value
+  }
+
   static get behaviour() {
     return this._behaviour
   }
 
   static set behaviour(value) {
-    if (!Object.values(behaviors).includes(value)) {
+    if (value == null) {
+      this._behaviour = value
+      return
+    }
+
+    if (typeof value !== 'object' || Array.isArray(value)) {
       throw new Error(`Invalid behaviour value: ${value}`)
     }
 
     this._behaviour = value
   }
 
+  static get hasBehaviourOverride() {
+    return this._hasBehaviourOverride
+  }
+
+  static set behaviourOverride(value) {
+    this._hasBehaviourOverride = !!value
+  }
+
   static get strategy() {
     if (this._strategy) {
       return this._strategy
@@ -204,6 +284,10 @@ class Webchat {
       /^rgba?\(\s*\d{1,3},\s*\d{1,3},\s*\d{1,3},?\s*(0|1|0?\.\d+)?\s*\)$/.test(value)
     )
   }
+
+  static isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+  }
 }
 
-export { behaviors, Webchat }
+export { modes, Webchat }

package/src/hellotext.js

@@ -28,10 +28,16 @@ class Hellotext {
     this.query = new Query()
 
     const businessData = await this.business.hydrate()
-    const webchatConfig = config.webchat === false ? false : {
-      ...((businessData && businessData.webchat) || {}),
-      ...(config.webchat || {}),
-    }
+    const webchatConfig = config.webchat === false ?
+      false :
+      this.mergeWebchatConfig((businessData && businessData.webchat) || {}, config.webchat || {})
+
+    const hasExplicitBehaviourOverride = (
+      config.webchat &&
+      config.webchat !== false &&
+      Object.prototype.hasOwnProperty.call(config.webchat, 'behaviour')
+    )
+    Configuration.webchat.behaviourOverride = hasExplicitBehaviourOverride
 
     if (webchatConfig && webchatConfig.id) {
       Configuration.webchat.assign(webchatConfig)
@@ -43,6 +49,28 @@ class Hellotext {
     }
   }
 
+  static mergeWebchatConfig(dashboardConfig, localConfig) {
+    return this.deepMergePlainObjects(dashboardConfig, localConfig)
+  }
+
+  static deepMergePlainObjects(base, override) {
+    const result = { ...base }
+
+    Object.entries(override).forEach(([key, value]) => {
+      if (this.isPlainObject(value) && this.isPlainObject(result[key])) {
+        result[key] = this.deepMergePlainObjects(result[key], value)
+      } else {
+        result[key] = value
+      }
+    })
+
+    return result
+  }
+
+  static isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+  }
+
   /**
    * Tracks an action that has happened on the page
    *

package/src/models/business.js

@@ -10,6 +10,8 @@ import BusinessesAPI from '../api/businesses'
 /**
  * @typedef {Object} BusinessWebchat
  * @property {String} [id] - Dashboard webchat id configured for the business.
+ * @property {Object} [appearance] - Dashboard appearance defaults for the webchat.
+ * @property {Object} [whatsapp] - Dashboard WhatsApp handoff defaults for the webchat.
  */
 
 /**