Skip to main content

JavaScript API

Control the Fyncall widget programmatically using the JavaScript API.

Global Object​

After the widget loads, the Fyncall object is available globally:

window.Fyncall

All API methods are available on this object.

Widget Control​

Open Widget​

Open the chat widget:

Fyncall.open();

Close Widget​

Close (minimize) the widget:

Fyncall.close();

Toggle Widget​

Toggle between open and closed:

Fyncall.toggle();

Check State​

Check if the widget is open:

const isOpen = Fyncall.isOpen();
console.log(isOpen); // true or false

Launcher Control​

Show Launcher​

Show the launcher button:

Fyncall.showLauncher();

Hide Launcher​

Hide the launcher button:

Fyncall.hideLauncher();

This also prevents the widget from being opened.

User Identification​

Identify User​

Associate the current visitor with user data:

Fyncall.identify({
  email: 'john@example.com',
  name: 'John Doe',
  userId: 'user_12345',
  phone: '+1234567890',
  // Custom attributes
  plan: 'premium',
  company: 'Acme Inc'
});

Parameters:

FieldTypeDescription
emailstringCustomer email address
namestringCustomer display name
userIdstringYour internal user ID
phonestringPhone number (E.164 format)
*anyCustom attributes

Example with custom attributes:

Fyncall.identify({
  email: 'customer@example.com',
  name: 'Jane Smith',
  userId: 'cust_abc123',
  // Custom data
  orderId: 'ORD-12345',
  cartValue: 199.99,
  vipStatus: true
});

Clear Identity​

Clear the current user's identity:

Fyncall.identify(null);

This resets the session to an anonymous visitor.

Event Tracking​

Track Events​

Send custom events for analytics:

Fyncall.track('event_name', {
  // Event properties
});

Common events:

// Page view
Fyncall.track('page_view', {
  page: '/products/widget',
  title: 'Premium Widget'
});

// Product viewed
Fyncall.track('product_viewed', {
  productId: 'prod_123',
  name: 'Premium Widget',
  price: 99.99
});

// Added to cart
Fyncall.track('added_to_cart', {
  productId: 'prod_123',
  quantity: 2,
  value: 199.98
});

// Purchase completed
Fyncall.track('purchase', {
  orderId: 'ORD-12345',
  total: 199.98,
  currency: 'USD'
});

Event Listeners​

Subscribe to Events​

Listen for widget events:

Fyncall.on('event_name', callback);

Available events:

EventDescription
readyWidget is fully loaded and ready
openWidget was opened
closeWidget was closed
messageNew message received
messageSentMessage was sent by customer
unreadCountUnread message count changed

Examples:

// Widget ready
Fyncall.on('ready', function() {
  console.log('Fyncall widget is ready');
});

// Widget opened
Fyncall.on('open', function() {
  console.log('Widget opened');
  // Track in analytics
  gtag('event', 'chat_opened');
});

// Widget closed
Fyncall.on('close', function() {
  console.log('Widget closed');
});

// New message received
Fyncall.on('message', function(message) {
  console.log('New message:', message);
});

// Message sent
Fyncall.on('messageSent', function(message) {
  console.log('Message sent:', message.text);
});

// Unread count changed
Fyncall.on('unreadCount', function(count) {
  console.log('Unread messages:', count);
  // Update custom badge
  document.getElementById('chat-badge').textContent = count;
});

Unsubscribe from Events​

Remove an event listener:

const handler = function(message) {
  console.log(message);
};

// Subscribe
Fyncall.on('message', handler);

// Unsubscribe
Fyncall.off('message', handler);

Localization​

Set Locale​

Change the widget language:

Fyncall.setLocale('es');

Supported locales:

LocaleLanguage
enEnglish (default)
esSpanish
frFrench
deGerman
ptPortuguese
itItalian
nlDutch
arArabic (RTL)

Queued Commands​

Before Widget Loads​

Commands are queued if called before the widget loads:

// These work even before the script loads
Fyncall.identify({ email: 'user@example.com' });
Fyncall.on('ready', function() {
  console.log('Ready!');
});

// Widget script loads later...
// <script async src="..."></script>

// Commands execute in order when ready

Full Example​

<!DOCTYPE html>
<html>
<head>
  <title>My Store</title>
</head>
<body>
  <button id="chat-button">Chat with us</button>
  <span id="unread-badge">0</span>

  <!-- Fyncall Widget -->
  <script async src="https://cdn.fyncall.com/widget/loader.js"
          data-fyncall-widget="fw_xxx"></script>

  <script>
    // Initialize Fyncall namespace
    window.Fyncall = window.Fyncall || { _q: [] };

    // Identify user (works even before widget loads)
    Fyncall.identify({
      email: 'customer@example.com',
      name: 'Customer Name',
      userId: '12345'
    });

    // Listen for events
    Fyncall.on('ready', function() {
      console.log('Widget ready!');
    });

    Fyncall.on('unreadCount', function(count) {
      document.getElementById('unread-badge').textContent = count;
    });

    // Custom chat button
    document.getElementById('chat-button').addEventListener('click', function() {
      Fyncall.open();
    });

    // Track page view
    Fyncall.track('page_view', {
      page: window.location.pathname
    });
  </script>
</body>
</html>

TypeScript Support​

Type definitions are available:

interface FyncallWidget {
  open(): void;
  close(): void;
  toggle(): void;
  isOpen(): boolean;
  showLauncher(): void;
  hideLauncher(): void;
  identify(user: FyncallUser | null): void;
  track(event: string, properties?: Record<string, any>): void;
  on(event: FyncallEvent, callback: Function): void;
  off(event: FyncallEvent, callback: Function): void;
  setLocale(locale: string): void;
}

interface FyncallUser {
  email?: string;
  name?: string;
  userId?: string;
  phone?: string;
  [key: string]: any;
}

type FyncallEvent = 'ready' | 'open' | 'close' | 'message' | 'messageSent' | 'unreadCount';

declare global {
  interface Window {
    Fyncall: FyncallWidget;
  }
}