Live Chat JavaScript API

Use the onWebChat JavaScript API to customize your chat widget and automate chat workflows. You can pass visitor data, set widget language, maximize or hide the widget, and more.

For example, you can send visitor details to the chat, set language by page, or open the widget programmatically when a user clicks a button.

Add your API code directly below the chat widget script, as shown on the right.




    <script type='text/javascript'>
        /* Paste your onWebChat widget installation snippet from the dashboard here. */
    </script>
    <script type='text/javascript'>
        /* Add your JavaScript API calls below, for example onWebChat.set() or onWebChat.get() */
    </script>

Set Visitor Information

You can set visitor details before or during a chat session. For example, setting the visitor name helps your team identify contacts in the Visitor List.

Use the following API calls to set a visitor's name, email, phone, and notes:



    onWebChat.set("name","Sarah Chen");
    onWebChat.set("email","sarah.chen@example.com");
    onWebChat.set("phone","+1 555 010 0142");
    onWebChat.set("notes","Returning visitor, requested an Enterprise trial");

Get Visitor Information

You can read the visitor's name, email, phone, and notes whenever those values were supplied through this JavaScript API, collected in the pre-chat form, or updated by agents in the dashboard.

You must call these functions after the widget has fully loaded. For example:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });



    onWebChat.get("name");
    onWebChat.get("email");
    onWebChat.get("phone");
    onWebChat.get("notes");

Set Widget Language

You can set the widget's language using the language code of any language enabled in your dashboard.

For example, use "en" for English, "es" for Spanish, and "fr" for French. If a specified language code is not enabled, the widget will fall back to your default language. You can manage your enabled and default languages in Settings > Languages.

Available language codes:

am ar az be bg bn bs ca cs da de dv dz el en es et fa fi fil fo fr he hi hr ht hu hy id is it ja ka kk kl km ko ky la lb lo lt lv mg mk mn ms mt my ne nl no pl ps pt ro ru rw si sk sl sm so sq sr sv sw tg th ti tk to tr uk ur uz vi zh zh-TW





    onWebChat.set("language","es");

Set Widget Appearance

You can control the widget's visibility and open state:

Use the max parameter with a value of 0 to minimize the widget, or 1 to maximize it.

To hide the widget entirely, use the show parameter with a value of 0. Use 1 to make it visible again.





    onWebChat.set("max",1);

    onWebChat.set("show",0);

Set Page Information

You can override the current page URL and title that are reported to the onWebChat dashboard:

Use the pageUrl parameter to set a custom URL. This is especially useful for single-page applications (SPAs) or custom routing where the browser URL doesn't change.

Use the pageTitle parameter to set a custom title that agents will see instead of the default browser page title.





    onWebChat.set("pageUrl","https://onwebchat.com/newPage");

    onWebChat.set("pageTitle","New title");

Get Widget Status

This function returns "online" or "offline" based on your current chat availability.

Make sure to call this after the widget has fully loaded. For example:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });




    onWebChat.get("status");

Get Connection Status

This returns true if the chat widget has an active socket connection to the server, and false otherwise.




    onWebChat.get("isConnected");

Get Widget Open/Closed State

This returns true if the chat widget is currently maximized (open), and false if it is minimized (closed).




    onWebChat.get("isMaximized");

Get Dialog ID

This returns the current active dialog ID, or 0 if there is no active chat session. It is useful for integrations that need to link a chat session to a CRM or ticketing system.




    onWebChat.get("dialogId");

Send Message

You can programmatically send a chat message on behalf of the visitor. This is useful for creating contextual help flows, such as automatically sending "I need help with my order" when a visitor clicks a specific button.

The message will appear in the chat exactly as if the visitor had typed it. Note that the widget must be fully loaded and connected before you can send a message.




    onWebChat.set("sendMessage","I need help with my order");

Set Department

You can pre-select a department for the visitor based on their current page context. For example, you can automatically route visitors on your pricing page to the "Sales" department, and visitors on your help page to "Support".

You can pass either the department name (as a string) or the department ID (as a number). If using the name, it must exactly match one of the departments configured in your dashboard.




    onWebChat.set("department","Sales");

Callback Functions

You can execute callback functions when specific chat events occur:

onClick runs when a visitor clicks the chat widget.

onMaximize runs when the widget is maximized (opened).

onMinimize runs when the widget is minimized (closed).

onTrigger runs when an automated trigger is activated.

onStartWriting runs when the visitor starts typing a message.

onNewMessage runs when a new message is sent or received. The callback receives two arguments: the message text, and the sender ("visitor", "agent", or "bot").

onEndChat runs when the chat session ends. The callback receives one argument indicating who ended it ("visitor", "agent", or "bot").

onChatStatusChange runs when the chat widget's status changes. The callback receives one argument indicating the new status ("online" or "offline").

onWebChatLoaded runs as soon as the chat widget finishes loading.




    onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });

    onWebChat.set("onMaximize",function(){ alert('chat maximized'); });

    onWebChat.set("onMinimize",function(){ alert('chat minimized'); });

    onWebChat.set("onTrigger",function(){ alert('trigger activated'); });

    onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });

    onWebChat.set("onNewMessage",function(msg, by){
        console.log('new message by ' + by + ': ' + msg);
    });

    onWebChat.set("onEndChat",function(endedBy){
        console.log('chat ended by ' + endedBy);
    });

    onWebChat.set("onChatStatusChange",function(status){
        console.log('agents are now ' + status);
    });

    onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });

Return to Support