Terra Smart Chat Widget Documentation

Here we list all available options for our Smart Widget. For the vast majority of people (yes, even if you are a developer) we recommend to use our Smart Widget Builder. With the Builder, you can see the changes in real-time! It covers all available options and not only it will give you the ready-to-use code to use in your website, but it will also configure the widget automatically and will help you with design tips (auto-color, contrast-checker and other utilities). Anyways, whether you use the Builder or not, you can always check this documentation to code it yourself or to check specific options.

Getting Started

To insert our widget into your page, you just need to insert two snippets. The first one is the widget code:

<script src="https://chat.terra.marketing/webchat.js"></script>

And the second one is the script to initialize the chat. For customers, it is as simple as the following:

<script>
    // If you want to show the user all the channels of your choice, instance a WebChat class.
    let widget = new WebChat({
        id: 'YOUR-ID'
    });

    // If you want your users to be able to talk directly from your website (live messages),
    // just instance a LiveWebChat class.
    let widget = new LiveWebChat({
        id: 'YOUR-ID'
    });

    // Just start the widget to show it!
    widget.start();
</script>

If you aren't a Terra customer yet, you just need to configure as follows:

<script>
    let widget = new WebChat();

    // You can add all the available channels you wish here
    widget
        .addChannel({
            type: Channel.Viber,
            url: 'viber://url'
        })
        .addChannel({
            type: Channel.WhatsApp,
            url: 'https://wa.me/number'
        })
    ;

    // Don't forget to start the widget to show it!
    widget.start();
</script>

Options

You can customize your widget to match your website or page colors and style. The Default Widget constructor accepts three parameters, while the Live Widget accepts two:

// WebChat class parameters
let widget = new WebChat([options], [channels], [wrapper]);

// LiveWebChat class parameters
let widget = new LiveWebChat([options], [wrapper]);

Reference

The first parameter (options) is an object which supports the following variables:

Example

let widget = new WebChat({
    theme: 'dark',
    position: 'right',
    animation: 'pulse',
    logo: 'https://yoursite.com/logo.png',
    description: 'Contact over your favorite channel!',
    style: {
        color: '#ff0000', // red
        iconsSameColorAsButton: true // icons will be red as well
    }
});

Channels (WebChat class only)

If you are using the WebChat class, you can add all channels supported by Terra on your widget on the second parameter, which is an array of objects with a predefined structure. Of course, there's no reason to have this parameter in the LiveWebChat class at all.

let widget = new WebChat([options], [channels], [wrapper]);

Reference

The second parameter (channels) is an array which supports the following objects inside:

Example

let widget = new WebChat({
    // Your options here (can be omitted to use the defaults)
},
[
    {
        type: Channel.Viber,
        url: 'viber://url'
    },
    {
        type: Channel.WhatsApp,
        url: 'https://wa.me/number'
    },
    // you can continue inserting channels as you wish
]);

Although we added this option in the constructor, we would recommend you to first initialize the var with the desired options and the use the following function to add your channels, as it helps with code readability:

let widget = new WebChat();

widget.addChannel({
    type: Channel.Viber,
    url: 'viber://url'
}).addChannel({
    type: Channel.WhatsApp,
    url: 'https://wa.me/number'
});

// You can concatenate this function multiple times to add all your channels.
// Way better, huh!?

Wrapper

You can add the widget inside a html element if you need to. We don't recommend you to use this option as it's probably will need to be used only for very specific reasons.

let widget = new WebChat([options], [channels], [wrapper]);

Reference

The wrapper parameter is a HTML Element.

Example

let widget = new WebChat({}, [], document.getElementById('your-element'));

Start

After you configured your widget as you want, you just need to call the start function to display it.

widget.start();

Remove Channel

If you are a Terra customer, the channels are added automatically to your widget. You might want to omit a few of them on the widget. All you need to do is to call this function before calling the start() function, passing the channel you desire to remove to it's parameter. You can also concatenate the function (just like the addChannel()) to remove multiple channels.

widget.removeChannel(Channel.SMS);

Reload Widget

As you might have noticed on the Widget Builder, the Widget can reload it's content dynamically without the need to restart it all (hot-reload all the way!). So, if by any reasons you do any kind of alterations after calling start() and want to display the changes to the user, all you need to do is to call this function. Please do notice that it's an async function.

widget.reload();

Errors

If anything goes wrong or you believe so, please take a look into the browser console. Most errors will show a very clear message on how to fix it. If you need support or find any bugs, please feel free to contact by clicking the button below and we'll be more than help to support you!