Belco Javascript API

Loading the Belco JavaScript library gives you access to the Belco Javascript object, which allows you to interact with the widget.

Initialize the widget

// Belco will automatically initialize when there's
// a global defined 'belcoConfig' variable

window.belcoConfig = {
  shopId: 'your-shop-id'

// Manually initialize the widget by omitting
// the 'belcoConfig' global variable.
// This can be usefull if you want to load
// some custom data with Javascript for example.

Belco.load(function() {
  var config = {
    shopId: 'your-shop-id'
  var customer = Belco.customer()
  if (customer && {
    config.customUrl = '' + 

Get the visitor id


// Sync with Google Analytics
Belco.once('ready', function() {
  analytics.once('ready', function () {
    try {
    } catch (e) { console.error(e) }

Opening the main Belco window.

Opening other windows.

Supported actions are chat, call, callback., [options])

// Open a specific conversation.'chat', {conversationId: 'uYgrWNqqaw2GybxH9'})

// Start new conversation about 'Product X' with a specific agent.'chat', {
  userId: 'uYgrWNqqaw2GybxH9',
  subject: 'Product X'

// Start a new conversation with tags.'chat', {tags: ['pricing']})

Closing the widget


Toggle the widget


Custom action buttons

If you want to control the widget with custom links or buttons, you can use the following html attribute to open specific windows.
Supported options are chat, call, callback.

<a href="#" data-belco-action="chat">Chat with us</a>

Event listeners

Currently we support the following events:
ready, open, close, started-conversation, placed-call, requested-callback, status-changed, cobrowse-session-started, cobrowse-session-ended

Add an event listener

Belco.on('event-name', function onEventName() {})

// Or trigger once
Belco.once('event-name', function onEventName() {})

// Trigger when chat status changes
Belco.on('status-changed', function onStatuschanged(e) {
  if (e.status === 'online') {
    // chat is online
  } else {
    // chat is offline

Remove an event listener'event-name', function onEventName() {});

Send a message on behalf of the visitor

Belco.sendMessage(options, [callback]);

    firstName: 'First name', // optional
  lastName: 'Last name', // optional
  email: '[email protected]', // optional
  tags: ['tag'], // Conversation tags, optional
  subject: 'Subject of the conversation', // optional
  message: 'The message'
}, function(err, conversationId) {
    if (err) {
  } else {

Example submitting a contact form using jQuery

<div id="contact">
  <form action="/" id="contact-form">
    <input name="department" type="radio" value="Sales" required />
    <input name="department" type="radio" value="Returns" required />

    <input name="firstName" type="text" required />
    <input name="lastName" type="text" required />
    <input name="email" type="email" required />
    <input name="subject" type="text" required />
    <textarea name="message" required></textarea>

    <button type="submit">Submit</button>

  jQuery(function($) {
    var $form = $('#contact-form')

    $form.on('submit', function(e) {

        firstName: $form.find('[name="firstName"]').val(),
        lastName: $form.find('[name="lastName"]').val(),
        email: $form.find('[name="email"]').val(),
        tags: [$form.find('[name="department"]').val()],
        subject: $form.find('[name="subject"]').val(),
        message: $form.find('[name="message"]').val()
      }, function(err, result) {
        if (err) {
        } else {
          $('#contact').html('<div class="success">Thanks! We received your message and we will contact you shortly.</div>') 

Connecting visitors to Google Analytics

Belco.once('ready', function() {
  analytics.once('ready', function () {

Updated 10 months ago

Belco Javascript API

Loading the Belco JavaScript library gives you access to the Belco Javascript object, which allows you to interact with the widget.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.