Messenger Javascript API

Introduction

The Messenger JavaScript API is available wherever the messenger embed code is included. This page is a reference for the API.

We've also provided sample code for popular use cases below.

The enchant variable

When you add the messenger to your website, the embed code we provide intializes the enchant variable. This is your entry point for all communications with the messenger running on the page.

push()

Takes a callback and executes it once the messenger is loaded. Any code that is intended to run immediately after the messenger loads (such as calls to config()) should be wrapped inside a callback sent to push().

Any callbacks sent to push() after the messenger loads are immediately executed.

enchant.push(function(){
  // code here
});

identify()

Specifies a name and email that will be used to pre-fill the live chat form and contact form.

Note: This overrides any previously known name or email unless the user of the messenger has customized it from the messenger interface. In other words, any user made changes are respected by default.

enchant.messenger.identify({
  name: "John",
  email: "john@example.com"
})

clearIdentity()

Forces the messenger to forget any previously known identity, even if customized by the user from the messenger interface.

For example, if the user updated their name or email on your website, you may want to force the messenger to be in sync. You would do that by calling clearIdentity() before calling identify().

enchant.messenger.clearIdentity()

config()

Set the configuration of the messenger. Available properties as follows:

Property	Type	Description
showKnowledgeBase	boolean	if false, the messenger will launch without an embedded knowledge base
showLauncher	boolean	if false, the default launcher is hidden

enchant.messenger.config({
  showKnowledgeBase: false
})

Note: config() can only be called before the messenger launches, so it must be sent in a push() with the page load.

open()

Opens the messenger window.

enchant.messenger.open()

close()

Closes the messenger window.

enchant.messenger.close()

chatAvailable()

Returns a boolean representing whether chat is available on the messenger. Chat is available on the messenger if the messenger is configured for chat and there is someone available to take the chat.

if(enchant.messenger.chatAvailable()){
  alert("Yes, chat is available!");
})

onChatAvailable()

Registers a callback to send a notification when there are any changes to chat availability of the messenger. Sends the current value of chatAvailable() to the callback.

enchant.messenger.onChatAvailable(function(available){
  if(available) {
    alert("chat is available!")
  } else {
    alert("chat is not available...")
  }
})

USE CASES

Setting your customer's identity

You can do this with your initial page load:

<script>
enchant.push(function(){
  enchant.messenger.identify({
    name: "John",
    email: "john@example.com"
  })
}) 
</script>

Note: the above code will override any name or email known to the messenger unless the user of the messenger has customized it from the messenger interface. To force the identity to be updated in all cases, do this:

<script>
enchant.push(function(){
  enchant.messenger.clearIdentity();
  enchant.messenger.identify({
    name: "John",
    email: "john@example.com"
  });
})
</script>

Custom launchers

Add a link which calls open() anywhere on your page:

<a href="javascript:enchant.messenger.open();">Get Help</a>

Or perhaps you want to style it differently if someone is available to chat:

<a class="custom-button" href="javascript:enchant.messenger.open();">We're Online!</a>

<script>
enchant.push(function(){
  enchant.messenger.onChatAvailableChange(function(available){
    if(available) {
      $('.custom-button').show();
    } else {
      $('.custom-button').hide();
    }
  }
});
</script>

To replace our default launcher, combine the above with:

<script>
enchant.push(function(){
  enchant.messenger.config({
    showLauncher: false
  })
})
</script>

Disabling knowledge base sometimes

Sometimes you don't want to load the messenger with an embedded knowledge base. For example, we use the same messenger on our marketing site without the knowledge base and in our app with the knowledge base. To do this, use the following configuration:

<script>
enchant.push(function(){
  enchant.messenger.config({
    showKnowledgeBase: false
  })
})
</script>