Customer Chat SDK

The Customer Chat JavaScript SDK allows you to access Facebook's Javascript SDK as well as control certain behaviors of the customer chat plugin such as opening and closing the dialog. These controls are dynamic and can be triggered without a page refresh.

Rate Limit

Each function in Customer Chat SDK is limited to 1 call per 5 seconds.

Install the SDK

If the Facebook Javascript SDK is already included in your website, all you'll need to do is set js.src equal to https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js as shown in the code snippet below.

(function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return;
  js = d.createElement(s); js.id = id;
  js.src = "https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));

If the Facebook Javascript SDK is not included in your website, you will need to see Facebook JavaScript SDK Quickstart for instructions, but remember to set js.src equal to https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js.

https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js requests a version of the Facebook Javascript SDK that includes the Customer Chat SDK. With this URL, you will still be able to access all of the Facebook Javascript SDK plus all features of the Customer Chat SDK.

Supported Controls

Showing the Plugin

Call this function to show the plugin on your page. You can use the shouldShowDialog parameter to decide if the dialog should also be shown.

For the plugin to stay hidden on initial page load, you have to set xfbml as false when initializing the SDK. Then you can call FB.XFBML.parse() to control when Customer Chat is loaded.

FB.CustomerChat.show(shouldShowDialog: boolean);

Hiding the Plugin

Call this function to hide the entire plugin on your page.

FB.CustomerChat.hide();

Showing the Dialog

Call this function to show the plugin dialog.

FB.CustomerChat.showDialog();

Hiding the Dialog

Call this function to hide the plugin dialog.

FB.CustomerChat.hideDialog();

Updating Greeting Text/Ref

This function allows you to update the greeting text and/or the ref params as specified in the Customer Chat reference. Call FB.CustomerChat.update with a JSON object with the new values.

These updates will not take effect after users enter a conversation with your business.

FB.CustomerChat.update({  
  logged_in_greeting: 'Hello There!',
  logged_out_greeting: 'Log in to Chat with Us',  
  ref: 'coupon_15',
});

Subscribing to Events

Plugin Load

This function provides the ability to subscribe to the plugin load event. It is emitted when the Facebook JavaScript SDK has been initialized and the plugin is about to load. The callback function is a required parameter.

At this point, the plugin is not necessarily mounted in the DOM. Calling the above plugin control functions might result in exceptions.

FB.Event.subscribe('customerchat.load', callback());

Plugin Show

This function provides the ability to subscribe to the plugin show event. The callback function is a required parameter.

FB.Event.subscribe('customerchat.show', callback());

Plugin Hide

This function provides the ability to subscribe to the plugin hide event. The callback function is a required parameter.

FB.Event.subscribe('customerchat.hide', callback());

Dialog Show

This function provides the ability to subscribe to the dialog show event. The callback function is a required parameter.

FB.Event.subscribe('customerchat.dialogShow', callback());

Dialog Hide

This function provides the ability to subscribe to the dialog hide event. The callback function is a required parameter.

FB.Event.subscribe('customerchat.dialogHide', callback());