Verloop.io Livechat APIs

This document provides the details needed to use the APIs in order to configure and start Verloop.io’s chat widget, further listen to event handlers and perform required actions. APIs are to be used only after adding the livechat widget script on the web page. Instructions to add the script can be found here.

Note: APIs are to be wrapped inside the Verloop() function. And multiple APIs can be called within a single Verloop function call. 

Verloop(function() {
    this.api();
    this.anotherApi();
    this.yetAnotherApi();
});

Verloop(function() {
    this.differentApi();
    this.newApi();
});

Configuration APIs

Widget can be configured, the user session can be managed, the state of the widget can be altered with the APIs listed below: 

Open the widget

Use the openWidget API to show the chat window and start the chat explicitly. 

Verloop(function() {
    this.openWidget();
});

Note: The floating chat bubble (button) does the same on CTA. This API isn’t necessary on a page where the button is presented.

Close the widget

Use the closeWidget API to close the chat window and the current chat session explicitly. 

Verloop(function() {
    this.closeWidget();
});

Start a particular recipe

Recipes are bot flows created via the dashboard. Use this API to load the chat using a particular recipe.   

Verloop(function() {
    this.setRecipe("recipe_id");
});

Recipe Id can be found from the recipe edit URL. For example: https://yourcompanyname.verloop.io/v2/recipes/recipe_id

If you are not setting any particular recipe, the default recipe will be started upon opening the widget. The default recipe is set on the dashboard. 

Note: Changes in the recipe won’t be reflected in an ongoing chat session.

Set user parameters

The user parameters like name, email and phone number can be set via the API. The corresponding blocks from the recipe will be skipped if these parameters are set.

Verloop(function() {
    this.setUserParams({
        name: "name_of_visitor",
        email: "email_of_visitor",
        phone: "phone_of_visitor"
    });
});

Set custom fields

The custom fields can be stored in a given scope. The accepted values for scope are “user” and “room“. The data is either persisted across chat sessions (or rooms) for a particular user or confined to a single chat session. Custom data comprises a key and value tuple. You can set custom fields as shown below.

Verloop(function() {
    this.setCustomField("key", "value", { scope: "user" });
});

These custom fields will also be sent to your server via the webhook block. Learn More

Set department

Use the set department API to configure the chat sessions on a particular department. 

Verloop(function() {
    this.setDepartment("department");
});

Clear department

Use the clearDepartment API to configure the subsequent chat sessions with no particular department. 

Verloop(function() {    
        this.clearDepartment();
});

Set user id

A user session can be initiated using the below API. A logged-in user’s identifier can be passed as an argument.

Verloop(function() {     
       this.setUserId("user_id");
});

All the chat sessions started with a particular user id will be linked to the user. Any user information saved as part of the recipe flow will be present against the chat window on the platform. If the chat session is ongoing (room is open), and when the chat window is opened with the user id, the session continues.    

Logout

The logout API is used to terminate the user session. It also closes the existing chat session. Can be used along with the setUserId API, and the onLogoutComplete handler shared below.

Verloop(function() {
    this.logout();
});

Handlers

Custom actions can be performed on events fired via the handlers provided below: 

On button clicks: 

Button click events on the chat recipe can be handled using the custom handler. 

Verloop(function() {
    this.onButtonClicked(function(info) {
        console.log(info);
    });
});

The parameter in the callback function will have both the button object and the message block object. Custom logic can be added in the callback here.

On chat started 

The handler is called once the chat session starts. 

Verloop(function() {    
        this.onChatStarted(function(args){
           args contain {roomId: <ID for the current room>}
            console.log("Chat Started", args.roomId)   
        });
});

On chat ended

The handler is called once the chat session ends. 

Verloop(function() {    
        this.onChatEnded(function(args){
            args contain {roomId: <ID for the current room>}
            console.log("Chat Ended", args.roomId)  
        });
});

On incoming message

The handler is called on every incoming message. The callback function parameter will provide the message text.

Verloop(function() {
    this.onIncomingMessage(function(message) {
        console.log(message);
    });
});

On logout 

This handler is called once a user has successfully logged out of the chat session. This handler works together with the logout API shared earlier.

Verloop(function() {
    this.onLogoutComplete(function() {
        console.log("Successfully logged the user out of the chat session");
    });
});

On chat maximized

This handler is called after the chat window is opened. Triggered when the openWidget API returns successfully.

Verloop(function() {
    this.onChatMaximized(function() {
        console.log("Successfully opened the chat window");
    });
});

On chat minimized

This handler is called after the chat window is closed. Triggered when the closeWidget API returns successfully.

Verloop(function() {
    this.onChatMinimized(function() {
        console.log("Successfully closed the chat window");
    });
});

On widget loaded

This handler is called when the chat window DOM is ready.

Verloop(function() {
    this.onWidgetLoaded(function() {
        console.log("Successfully loaded the widget");
    });
});