@developer.notchatbot/webchat 1.2.9 → 1.2.10

package/README.md

@@ -337,6 +337,64 @@ window.mountEmbedChat('embed-small');   // Remounts the chat in the same element
 
 ---
 
+### Listen to lifecycle & message events (🆕)
+
+We emit **custom browser events** so you can capture interactions and feed them into Google Tag Manager, Google Analytics, Meta Pixel, or any other analytics tool.
+
+| Widget | Event name | Fired when | `detail` payload |
+|--------|------------|------------|------------------|
+| WebChat | `WebChatOpened` | The floating chat is opened | `{ conversationId }` |
+| WebChat | `WebChatClosed` | The floating chat is closed | `{ conversationId }` |
+| WebChat | `WebChatMessageSent` | The user sends one or more messages | `{ messages: Message[] }` |
+| WebChat | `WebChatMessageReceived` | A message is received from the server | `{ message: Message, role: 'assistant' \| 'employee' }` |
+| EmbedChat | `EmbedChatMessageSent` | The user sends a message | `{ message: Message }` |
+| EmbedChat | `EmbedChatMessageReceived` | A message is received | `{ message: Message, role: 'assistant' \| 'employee' }` |
+
+`Message` follows the same interface used internally by the widget (id, text, sender, timestamp, etc.).
+
+#### Quick example
+```js
+window.addEventListener('WebChatOpened',  e => console.log('WebChat opened', e.detail));
+window.addEventListener('WebChatClosed',  e => console.log('WebChat closed', e.detail));
+window.addEventListener('WebChatMessageSent', e => console.log('Sent', e.detail.messages));
+window.addEventListener('WebChatMessageReceived', e => {
+  const { role, message } = e.detail;
+  console.log('Received', role, message);
+});
+```
+
+#### Google Tag Manager / Google Analytics (GA4)
+Push data directly to the **dataLayer** and create a trigger in GTM:
+```js
+window.addEventListener('WebChatMessageSent', e => {
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({
+    event: 'webchat_message_sent',
+    messages: e.detail.messages,
+    conversationId: e.detail.messages[0]?.conversationId || null
+  });
+});
+```
+Then in GTM, add a **Custom Event** trigger called `webchat_message_sent` and link it to a GA4 event tag.
+
+#### Meta / Facebook Pixel
+```js
+window.addEventListener('WebChatOpened', () => {
+  if (window.fbq) {
+    fbq('trackCustom', 'WebChatOpened');
+  }
+});
+
+window.addEventListener('WebChatMessageReceived', e => {
+  if (window.fbq) {
+    fbq('trackCustom', 'WebChatMessageReceived', {
+      role: e.detail.role
+    });
+  }
+});
+```
+These events make it easy to measure engagement and conversions driven by the chat widget without modifying its source code.
+
 ### Change position and padding dynamically (WebChat)
 
 #### 1. Change position and margin globally (flat)