Events

The SDK dispatches custom DOM events on the window object. Listen for these events to react to widget state changes in your application.

Event Reference

Event	Fires When	Payload
lovina:ready	Widget iframe has loaded and is ready	undefined
lovina:opened	Chat panel opens	undefined
lovina:closed	Chat panel closes	undefined
lovina:on-message	A new message is received	{ message: Message }
lovina:error	An error occurs in the widget	{ code: string, message: string }
lovina:postback	A postback button is clicked	{ postback: object }

Payload Structure

Events with payloads deliver data via the standard event.detail property:

window.addEventListener('lovina:on-message', function(event) {
  var payload = event.detail;
  // payload.message contains the Message object
});

Message Object

The lovina:on-message event provides a Message object with these fields:

Field	Type	Description
id	string	Unique message ID
content	string	Message text content
messageType	'incoming' | 'outgoing'	Direction of the message
contentType	'text' | 'image' | 'file'	Content type
status	'sent' | 'delivered' | 'read'	Delivery status
createdAt	string	ISO 8601 timestamp
attachments	Attachment[]	File attachments, if any

Error Object

The lovina:error event provides:

Field	Type	Description
code	string	Error code identifier
message	string	Human-readable error description

Usage Examples

Wait for the Widget to Be Ready

Always wait for lovina:ready before calling API methods:

window.addEventListener('lovina:ready', function() {
  console.log('Lovina widget is ready');

  window.$lovina.setUser('user-123', {
    name: 'Jane Doe',
    email: 'jane@example.com',
  });
});

React to New Messages

window.addEventListener('lovina:on-message', function(event) {
  var message = event.detail.message;
  console.log('New message:', message.content);

  // Show a browser notification when the page is not visible
  if (document.hidden && Notification.permission === 'granted') {
    new Notification('New message from support', {
      body: message.content,
    });
  }
});

Track Widget Open/Close for Analytics

window.addEventListener('lovina:opened', function() {
  analytics.track('chat_opened');
});

window.addEventListener('lovina:closed', function() {
  analytics.track('chat_closed');
});

Handle Errors

window.addEventListener('lovina:error', function(event) {
  console.error('Lovina error:', event.detail.code, event.detail.message);

  // Report to your error tracking service
  Sentry.captureMessage('Lovina SDK error: ' + event.detail.message, {
    extra: { code: event.detail.code },
  });
});

Handle Postback Buttons

Postback events fire when a user clicks a structured button (e.g., quick replies, card actions):

window.addEventListener('lovina:postback', function(event) {
  var postback = event.detail.postback;
  console.log('Postback clicked:', postback);
});

Framework Integration

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const handleReady = () => {
      window.$lovina.setUser('user-123', { name: 'Jane' });
    };

    const handleMessage = (event) => {
      console.log('Message:', event.detail.message.content);
    };

    window.addEventListener('lovina:ready', handleReady);
    window.addEventListener('lovina:on-message', handleMessage);

    return () => {
      window.removeEventListener('lovina:ready', handleReady);
      window.removeEventListener('lovina:on-message', handleMessage);
    };
  }, []);

  return <div>My App</div>;
}

Vue

<script setup>
import { onMounted, onUnmounted } from 'vue';

function handleMessage(event) {
  console.log('Message:', event.detail.message.content);
}

onMounted(() => {
  window.addEventListener('lovina:on-message', handleMessage);
});

onUnmounted(() => {
  window.removeEventListener('lovina:on-message', handleMessage);
});
</script>