JavaScript API

Customize and control the Olark chat box from your site's code.

We offer a powerful Javascript API that gives you flexibility and control over the behavior of the Olark chat box. You can decide, how, when and where to display the chat box on your site, as well as view and update visitor information.

Debugging

Use the !develop command from the agent console to reveal helpful debug tools on the visitor’s chatbox. This is useful for debugging.

Where to place code

Configuration calls must be used when the chatbox first loads on a page. Put configuration calls before olark.identify:

/* custom configuration goes here (www.olark.com/documentation) */
// ⟶ Your configuration here
olark.identify(‘1234-456-78-9810’);

We encourage developers to write their own JavaScript to extend the Olark functionality on their sites. We’re very excited when we see examples of the API used in creative ways. Let us know if you have an interesting implementation and we may publish it. Email support@olark.com with your creations!

Support

We’ll do our best to help with any questions you have. The API is intended to be self-serve for web developers, so we’re not able to write or debug your own code.

Localization

You can translate the chat box into any language in your text settings and editing the text.

If you need to work with multiple languages, use our API to localize language strings.

Chat box behavior

Show the chatbox olark('api.box.show'); Unhide the chat box Hide the chatbox olark('api.box.hide'); Hide the chat box Expand the chatbox olark('api.box.expand'); Expand the chat box Minimize the chatbox olark('api.box.shrink'); Minimize the chat box Dynamically change the chatbox language olark('api.box.setLocale', 'en-US') Dynamically change the chatbox language On chatbox show

olark('api.box.onShow', function() {
	// Your callback function
});

Monitor when the chat box unhides On chatbox hide

olark('api.box.onHide', function() {
	// Your callback function
});

Monitor when the chat box is hidden On chatbox expand

olark('api.box.onExpand', function() {
	// Your callback function
});

Monitor when the chat box expands On chatbox minimize

olark('api.box.onShrink', function() {
	// Your callback function
});

Monitor for the chat box minimizing

Chat box appearance

Change Chatbox Position olark.configure('system.hb_position', 'left'); Change chatbox position Change Chatbox Size olark.configure('system.hb_chatbox_size', 'sm'); Change chatbox size Change Font Family

olark.configure('system.hb_custom_style', { 
	general: { 
		fonts: ['Bitter', 'serif'], 
		corners: '', 
		secondaryColor: '' 
	} 
});

Change the font of the chatbox Change Text Position olark.configure('system.right_to_left', true ); Change text position Change the Border Radius

olark.configure('system.hb_custom_style', { 
	general: { 
		fonts: [''], 
		corners: 'soft', 
		secondaryColor: '' 
	} 
});

Change the border radius for the corners of the chatbox Change the Color of Visitor Messages

olark.configure('system.hb_custom_style', { 
	general: { 
		fonts: [''], 
		corners: '', 
		secondaryColor: '#ffe6ff' 
	} 
});

Change the color of visitor messages Disable the Mobile Chatbox olark.configure('system.hb_disable_mobile', true ); Disbale the Mobile Chatbox Floating Chatbox olark.configure('system.hb_detached', true ); Floating chatbox Set Dark Theme olark.configure('system.hb_dark_theme', true ); Set dark or light theme Set Theme Color olark.configure('system.hb_primary_color', string); Set theme color Show as Tab olark.configure('system.hb_show_as_tab', true ); Show as tab Show Button Text olark.configure('system.hb_show_button_text', true ); Show button text

Configure the chat box

Chat conversation

On chatbox load

olark('api.chat.onReady', function(){
	// Your callback function
});

Check Olark has loaded Change operator group

olark('api.chat.setOperatorGroup', {
	group: // Group ID from https://www.olark.com/op
});

Lock the visitor to an operator group On operators available

olark('api.chat.onOperatorsAvailable', function() {
	// Your callback function
});

Trigger for when operators are available On operators unavailable

olark('api.chat.onOperatorsAway', function() {
	// Your callback function
});

Trigger for when operators are away On conversation start

olark('api.chat.onBeginConversation', function() {
	// Your callback function
});

Monitor when a conversation begins On message to operator

olark('api.chat.onMessageToOperator', function(event) {
	// Your callback function
});

Check for a message being sent to the operator On message to visitor

olark('api.chat.onMessageToVisitor', function(event) {
	// Your callback function
});

Check for a message being sent to the visitor On operator command

olark('api.chat.onCommandFromOperator',
	function(event) {
		// Callback function
	}
);

Monitor for an operator using a command Send message to visitor olark('api.chat.sendMessageToVisitor', options ); Send a message to the visitor Send operator notification

olark('api.chat.sendNotificationToOperator', {
	body: string
});

Send a notification to the operator Send visitor notification

olark('api.chat.sendNotificationToVisitor', {
	body: string
});

Send a notification to the visitor Offline message sent

olark('api.chat.onOfflineMessageToOperator', function(event) {
	// Your callback function
});

Monitor for an offline message being sent

Visitor information

Get visitor details olark('api.visitor.getDetails', callback); Read the visitor informaton Update visitor nickname

olark('api.chat.updateVisitorNickname', {
	snippet: '',
	hidesDefault: true
});

Set the visitor's nickname Update visitor status

olark('api.chat.updateVisitorStatus', {
	snippet: ''
});

Set the visitor's status Update visitor name

olark('api.visitor.updateFullName', {
	fullName: string
});

Set the visitor's name Update visitor email

olark('api.visitor.updateEmailAddress', {
	emailAddress: string
});

Set the visitor's email Update visitor phone

olark('api.visitor.updatePhoneNumber', {
	phoneNumber: string
});

Set the visitor's phone number Update CRM custom fields

olark('api.visitor.updateCustomFields', {
	internalCustomerId: string
});

Set custom fields for the visitor

Pre-chat survey

Require name olark.configure('system.ask_for_name', 'hidden' ); Require visitors fill out their name before chatting Require email olark.configure('system.ask_for_email', 'hidden' ); Require visitors fill out their email before chatting Require phone number olark.configure('system.ask_for_phone', 'hidden' ); Require visitors fill out their phone before chatting Add a custom prechat survey

olark.configure('system.custom_prechat', [
	{ 
		is_required: false, 
		label: 'What can we help with today?', 
		placeholder_text: 'I need help with ...' , 
		type: 'textarea' 
	} 
]);

Dynamically add questions to your prechat survey

Greeter

Switch on the Greeter olark.configure('WelcomeAssist.welcome_new_visitors', true ); Switch on the Greeter Enable Greeter olark.configure('features.greeter', true ); Enable Greeter Set Greeter delay in seconds olark.configure('WelcomeAssist.welcome_delay_in_seconds', integer ); Set the Greeter delay Set Greeter Welcome Messages olark.configure('WelcomeAssist.welcome_messages', ['hello world', 'another message!', 'a 3rd message!']); Set the Greeter Welcome Messages Notify operators of first-time visitors olark.configure('WelcomeAssist.notify_operator_of_new_visitors', true ); Enable notification of arrival using Greeter

Attention Grabber

Enable Attention Grabber olark.configure('features.attention_grabber', true ); Enable the Attention Grabber Online Attention Grabber image olark.configure('CalloutBubble.bubble_image_url', 'path/to/file' ); Online Attention Grabber image Offline Attention Grabber image olark.configure('CalloutBubble.bubble_image_url_offline', 'path/to/file' ); Offline Attention Grabber image Attention Grabber image width olark.configure('CalloutBubble.bubble_width', integer ); Attention Grabber image width Attention Grabber image height olark.configure('CalloutBubble.bubble_height', integer ); Attention Grabber image height Attention Grabber animation olark.configure('CalloutBubble.slide', true ); Enable the Attention Grabber animation

Google Analytics

Enable Google Analytics olark.configure('features.google_analytics', true ); Enable Google Analytics Set Google Analytics ID olark.configure('system.google_analytics_id', string ); Set your Google Analytics ID

Targeted Chat

Define Targeted Chat rules olark('api.rules.defineRule', { options }); Create Targeted Chat rules