Introduction

This guide shows you how to get started with the AutobotX Chat Web SDK. The Web SDK gives businesses and developers the flexibility to build and customize a chat experience that meets their specific design and brand requirements.

The SDK is exposed as window.abxChat. All API methods, events, and constants are accessible through this object. An internal full-form alias window.AutobotXChatWidget is also available but abxChat is the recommended way to interact with the SDK.

Concepts

The Web SDK is a JavaScript library embedded via a script tag. It automatically handles the real-time connection with the chat servers and manages the visitor session. It provides a list of events and convenient methods so you can focus on integration.

API Conventions

• Getter methods (e.g. .getVisitorInfo()) return values synchronously.
• Setter / action methods (e.g. .setVisitorInfo()) are asynchronous and accept an optional Node.js-style callback function(err, data) { ... }.
• .on() and .off() (or .un() on the shorthand alias) are the main methods to register/de-register real-time events.

// Getter - synchronous
console.log(abxChat.getVisitorInfo());

// Setter - async with optional callback
abxChat.setVisitorInfo(
  { display_name: 'Jane' },
  function(err) {
    if (!err) {
      console.log('Updated:', abxChat.getVisitorInfo());
    }
  }
);

// Callback is optional - this also works:
abxChat.setVisitorInfo({ display_name: 'Jane' });

Event Registry

The SDK provides an event registry for real-time updates. Register listeners with .on() and remove them with .off(). The .on() method returns an unsubscribe function for convenience.

function listener(detail) { /* ... */ }

// Register
abxChat.on('connection_update', listener);

// De-register (option 1)
abxChat.off('connection_update', listener);

// De-register (option 2) - using .un() alias
abxChat.un('connection_update', listener);

// De-register (option 3) - using return value
var unsub = abxChat.on('chat', listener);
unsub(); // removes the listener

Error Handling

There are two types of errors:

1. Validation errors — occur when methods are called with invalid parameters. These are logged to the console unless suppressed via suppress_console_error: true in init(). You can also capture them via the 'error' event.
2. Execution errors — passed as the first argument to the callback function (err). If successful, err is null.

abxChat.init({
  account_key: 'YOUR_API_TOKEN',
  suppress_console_error: true
});

// Or capture errors via the event
abxChat.on('error', function(err) {
  console.error('SDK Error:', err);
});

Chat Participants

Every chat participant has a unique nick property. For visitors it is 'visitor'. For agents it follows the format 'agent:<agent-id>'.

Guide

Getting Started

Add the embed script to your page. This creates the widget iframe and exposes window.abxChat and window.abxChat.

<!-- Begin AutobotX Chat Widget -->
<script type="text/javascript">
  window.abxChat || (function(d, s, id) {
    var w = (window.abxChat = function(c) { w._.push(c); });
    w._ = [];
    w.q = function() { w._.push([].slice.call(arguments)); };
    var m = ['init','open','close','toggle','on','off','identify',
      'sendChatMsg','sendTyping','setVisitorInfo','sendOfflineMsg',
      'addTags','removeTags','endChat','sendChatRating','sendChatComment',
      'sendFile','sendEmailTranscript','sendVisitorPath','updateConfig'];
    m.forEach(function(k) { w[k] = function() {
      w._.push([k].concat([].slice.call(arguments))); }; });
    var e = d.createElement(s);
    e.async = true; e.id = id;
    e.src = "https://agent-builder.autobotx.ai/api/widget?key=YOUR_KEY";
    var t = d.getElementsByTagName(s)[0];
    t.parentNode.insertBefore(e, t);
  })(document, "script", "autobotx-chat-widget");
</script>
<!-- End AutobotX Chat Widget -->

Place this snippet before the closing </body> tag. You can safely call SDK methods immediately — they will be queued and executed once the script loads:

// These work BEFORE the script finishes loading:
abxChat.open();
abxChat.on('connection_update', function(status) {
  console.log('Connection:', status);
});

Initializing the SDK

If you need to pass additional configuration (e.g. a different API token or suppress errors), call init():

abxChat.init({
  account_key: 'YOUR_API_TOKEN',
  suppress_console_error: false
});

// Wait for connection before consuming APIs
abxChat.on('connection_update', function(status) {
  if (status === 'connected') {
    // Ready to use API methods
    console.log('Account status:', abxChat.getAccountStatus());
  }
});

Chat

A chat starts when the visitor or agent sends the first message. When this happens, a chat.memberjoin event fires. Use sendChatMsg() to send messages and endChat() to end the session.

// Send a message
abxChat.sendChatMsg('Hello!', function(err) {
  if (!err) console.log('Message sent');
});

// Listen for incoming messages
abxChat.on('chat', function(event_data) {
  if (event_data.type === 'chat.msg') {
    console.log(event_data.display_name + ': ' + event_data.msg);
  }
});

Typing

// Tell agents the visitor is typing
abxChat.sendTyping(true);

// Listen for agent typing
abxChat.on('chat', function(event_data) {
  if (event_data.type === 'typing') {
    console.log('Agent typing:', event_data.typing);
  }
});

Chat Transcript

Visitors can request the transcript to be emailed when the chat ends:

abxChat.sendEmailTranscript('visitor@example.com', function(err) {
  if (!err) console.log('Transcript scheduled');
});

Chat Feedback

// Rate the chat
abxChat.sendChatRating('good', function(err) { /* ... */ });

// Leave a comment
abxChat.sendChatComment('Very helpful!', function(err) { /* ... */ });

Attachments

// Send a file (max 20MB)
var fileInput = document.getElementById('fileInput');
abxChat.sendFile(fileInput.files[0], function(err, data) {
  if (!err) {
    console.log('File URL:', data.url);
  }
});

// Receive attachments via 'chat' event
abxChat.on('chat', function(event_data) {
  if (event_data.type === 'chat.file') {
    console.log('Attachment:', event_data.attachment.url);
  }
});

Offline Messages

abxChat.sendOfflineMsg({
  name: 'John',
  email: 'john@example.com',
  phone: '12345678',
  message: 'Please get back to me'
}, function(err) {
  if (!err) console.log('Offline message sent');
});

API Reference

The complete list of API methods available on abxChat (and abxChat).

abxChat.init({
  account_key: 'YOUR_API_TOKEN',
  suppress_console_error: false
});

var status = abxChat.getAccountStatus();
// 'online'

var conn = abxChat.getConnectionStatus();
// 'connected'

var info = abxChat.getVisitorInfo();
// { display_name: 'John', email: 'john@example.com', phone: '' }

abxChat.setVisitorInfo({
  display_name: 'Jane Doe',
  email: 'jane@example.com'
}, function(err) {
  if (!err) console.log('Updated');
});

// Without callback (also valid)
abxChat.setVisitorInfo({ display_name: 'Jane' });

abxChat.sendVisitorPath({
  title: 'Pricing',
  url: 'https://example.com/pricing'
});

var pos = abxChat.getQueuePosition();
// 3

var depts = abxChat.getAllDepartments();
// [{ id: 1, name: 'Sales', status: 'online' }, ...]

var dept = abxChat.getDepartment(1);
// { id: 1, name: 'Sales', status: 'online' }

abxChat.setVisitorDefaultDepartment(1, function(err) {
  if (!err) console.log('Default department set');
});

abxChat.sendChatMsg('Hello!', function(err) {
  if (!err) console.log('Sent');
});

abxChat.sendFile(file, function(err, data) {
  if (!err) {
    console.log('Uploaded:', data.name, data.url);
  }
});

abxChat.sendOfflineMsg({
  name: 'John',
  email: 'john@example.com',
  phone: '12345678',
  message: 'I need help with my order'
}, function(err) {
  if (!err) console.log('Offline message sent');
});

abxChat.addTags(['vip', 'premium'], function(err) {
  if (!err) console.log('Tags added');
});

abxChat.removeTags(['vip'], function(err) { /* ... */ });

abxChat.sendTyping(true);  // visitor is typing
abxChat.sendTyping(false); // visitor stopped

var info = abxChat.getChatInfo();
// { rating: 'good', comment: 'Very helpful' }

abxChat.sendChatRating('good', function(err) { /* ... */ });

abxChat.sendChatComment('Great support!', function(err) { /* ... */ });

if (abxChat.isChatting()) {
  console.log('Chat in progress');
}

var log = abxChat.getChatLog();
// Returns a Promise that resolves to an array of chat messages

var agents = abxChat.getServingAgentsInfo();
// [{ nick: 'agent:1', display_name: 'Agent Smith', ... }]

var hours = abxChat.getOperatingHours();
// { enabled: true, type: 'account', timezone: 'America/New_York', ... }

abxChat.sendEmailTranscript('john@example.com', function(err) {
  if (!err) console.log('Transcript scheduled');
});

abxChat.fetchChatHistory(function(err, data) {
  if (!err) {
    console.log('Fetched', data.count, 'items');
    console.log('Has more:', data.has_more);
  }
});

abxChat.markAsRead();

if (abxChat.getConnectionStatus() === 'closed') {
  abxChat.reconnect();
}

abxChat.endChat(
  { clear_dept_id_on_chat_ended: true },
  function(err) { /* ... */ }
);

abxChat.logout();

Constants

var regex = abxChat.EMAIL_REGEX;
// /^[^\s@]+@[^\s@]+\.[A-Z|a-z]{2,}\b/

Internal rate-limiting constants:

Events

Real-time events are emitted and can be listened to via .on(event_name, handler) and removed via .off(event_name, handler).

abxChat.on('account_status', function(status) {
  console.log('Account is now:', status);
});

abxChat.on('connection_update', function(status) {
  if (status === 'connected') {
    // Safe to use API methods
  }
});

abxChat.on('department_update', function(dept) {
  console.log(dept.name, 'is', dept.status);
});

abxChat.on('visitor_update', function(visitorInfo) {
  console.log('Visitor:', visitorInfo.display_name);
});

abxChat.on('agent_update', function(agentInfo) {
  console.log('Agent joined:', agentInfo.display_name);
});

'chat' Event

The chat event encompasses all real-time chat activity. The event_data.type property indicates the specific type:

abxChat.on('chat', function(e) {
  if (e.type === 'chat.msg') {
    console.log(e.display_name + ': ' + e.msg);
  }
});

abxChat.on('chat', function(e) {
  if (e.type === 'chat.file') {
    console.log('File:', e.attachment.name, e.attachment.url);
  }
});

abxChat.on('chat', function(e) {
  if (e.type === 'chat.queue_position') {
    console.log('Queue position:', e.queue_position);
  }
});

abxChat.on('chat', function(e) {
  if (e.type === 'chat.memberjoin') {
    console.log(e.display_name + ' joined');
  }
});

abxChat.on('chat', function(e) {
  if (e.type === 'chat.memberleave') {
    console.log(e.display_name + ' left');
  }
});

abxChat.on('chat', function(e) {
  if (e.type === 'typing') {
    console.log(e.nick, 'typing:', e.typing);
  }
});

abxChat.on('history', function(event_data) {
  if (event_data.type === 'chat.msg') {
    console.log('History message:', event_data.msg);
  }
});

abxChat.on('error', function(err) {
  console.error('SDK error in', err.context, ':', err.message);
});

Pre-load Queue & Aliases

Pre-load Command Queue

The embed snippet creates abxChat as a lightweight stub with method queuing. You can call SDK methods before the script finishes loading — they are queued and automatically replayed once the SDK is ready. Both styles work:

// Style 1: Direct method calls (queued automatically)
abxChat.open();
abxChat.on('connection_update', function(status) {
  console.log(status);
});
abxChat.sendChatMsg('Hello!');

// Style 2: Callback wrapper (also queued)
abxChat(function() {
  // Runs once SDK is fully loaded
  console.log('Status:', abxChat.getAccountStatus());
});

.un() Alias

abxChat.un(event, handler) is a convenience alias for .off(event, handler). Both do the same thing:

// These are equivalent:
abxChat.off('chat', handler);
abxChat.un('chat', handler);

Alternate Global Name

The SDK is also accessible via window.AutobotXChatWidget (internal full-form name). Both globals point to the same API. Use abxChat in your integration code.

Extended API

These are additional methods beyond the core chat SDK surface.

Widget Control

// Open the widget
abxChat.open();

// Identify a user
abxChat.identify({
  name: 'John Doe',
  email: 'john@example.com',
  id: '12345'
});

Tags (Extended)

Tracking & Privacy

Capabilities