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 && customer.email) {
    config.customUrl = 'https://shopbackend.com/customers?search=' + customer.email 
  }
  
  Belco.init(config)
})

Get the visitor id

Belco.anonymousId()

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

Opening the main Belco window.

Belco.open()

Opening other windows.

Supported actions are chat, call, callback.

Belco.open(action, [options])

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

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

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

Closing the widget

Belco.close()

Toggle the widget

Belco.toggle()

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

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

Tracking events

📘
When tracking events it's important to run the track call after the init method, other wise events might not get tracked.

Belco.load(function() {
  var config = {
   shopId: '[your shopid]' 
  }
  Belco.init(config)
  
  Belco.track('Order Completed', {
    'orderId': '1234',
    'date': '2021-01-01T00:00:00Z',
    'total': 10.00,
    'status': 'completed'
  })
})

Send a message on behalf of the visitor

In case you want to automatically send out an message to Belco you can do this by using the sendMessage function.

Sending out a message without a conversationId field would always initialize a new conversation.

In order to get the conversationId to continue the message you can call the getConversationId function, this would return a undefined on a non-existing conversation, or an id when there is an active chat happening in the browser session.

Belco.sendMessage(options, [callback]);

Belco.getConversationId();

Belco.sendMessage({
  conversationId: 'id_of_conversation', // optional
 	firstName: 'First name', // optional
  lastName: 'Last name', // optional
  email: 'name@example.com', // optional
  tags: ['tag'], // Conversation tags, optional
  subject: 'Subject of the conversation', // optional
  message: 'The message'
}, function(err, conversationId) {
 	if (err) {
  	console.error(err) 
  } else {
    // this Id can be used in the next call, or get it through getConversationId() method
    console.log(conversationId) 
  }
});

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>
  </form>
</div>

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

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

      Belco.sendMessage({
        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) {
          alert(err)
        } else {
          $('#contact').html('<div class="success">Thanks! We received your message and we will contact you shortly.</div>') 
        }
      })
    })
  })
</script>

Example of submitting a new conversation through callbacks

This is for when you want to send out a new conversation and send a second message directly.

Belco.sendMessage({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com',
  message: 'Hello I want to get in contact',
}, function (err, conversationId) {
  if (err) {
    alert(err)
  } else {
    // here you use the conversationId from the callback to sendout a second message.
    Belco.sendMessage({
      conversationId, 
      message: 'could you please send me an email?'
    })
    Belco.sendMessage({
      conversationId,
      message: 'Thanks :D'
    })
  }
}

Example of submitting to a existing conversation, or as backup a new one.

In this flow you can add messages on behave of the visitor on an existing conversation, or a new one if none was initialized.

let conversationId = Belco.getConversationId(); // this could be undefined or a string of an id.

Belco.sendMessage({
   conversationId,
   message: "Form answer A'
})

// some other code in between waiting for the second click

// Check if the previous conversationId was undefined,
//  and update it to the current conversationId
if (conversationId === undefined) {
  conversationId = Belco.getConversationId();
}
// send out the second message
Belco.sendMessage({
  conversationId,
  message: "second answer B'
})


// or you can also do the following format, calling getConversationId() on every call.
Belco.sendMessage({
  conversationId: Belco.getConversationId(),
  message: "this message would trigger a message on a new conversation or existing one if there is any"
})

Get the ID of the conversation

Sometimes you want to do more with the data and in case you want to extract the conversationId from your webpage, you can use the getConversationId function.
This can be used as a input for the belco api or sending additional messages on behave of the visitor.

/**
* Get the conversation Id: 
* null       = no active conversation in the current session
* 'randomId' = the current Id of the conversation. 
**/
Belco.getConversationId();

Connecting visitors to Google Analytics

Belco.once('ready', function() {
  analytics.once('ready', function () {
     analytics.setAnonymousId(Belco.anonymousId());
  });
})