Webchat API

Developers can customize the appearance and functionality of Proto's Webchat channel.

Deploy snippet

To deploy Webchat to your website, copy and paste the deploy snippet found in CONFIGURATION tab of your Webchat channel.

<html>
  <body>
    <script type="text/javascript" src="https://app.proto.cx/webchat/client.js"></script>
    <script type="text/javascript">
      window.addEventListener('DOMContentLoaded', function() {
        Proto.init(
          {
            gwId: '<WEBCHAT-CHANNEL-ID>',
            env: ''
          },
          function() { Proto.show(); }
        );
      });
    </script>
  </body>
</html>

📘

Note

Place the deploy snippet before the </body> tag of your HTML file.

Methods

  1. Initialize webchat:
  • The Proto.init(options={}, callback=null) will create websocket connection to the Proto server
  • Also, an iframe element will be injected to the host's HTML
  • The following table shows the fields that can be include in the options

Field

Type

Required

Description

gwId

string

Compulsory

Webchat Channel ID that can be found in Webchat > Settings page.

env

string

Optional

To be leave as empty string "" (default).

lang

string

Optional

The language code of the webchat UI. The Master language of the bot is the default language.

ateamId

string

Optional

The preferred team to accept new incoming chat. It this field is empty, bot will handle the chat.

humanUid

string

Optional

The access token of current visitor. The bot will use this token to fetch data from your server.

📘

Note

Add ateamId only if you would like to use livechat functionality only (incoming chats will be automatically directed to agents and not the chatbot).

  • The callback will be be executed when the Webchat is fully loaded
  • The following step show the Proto's script that can be use into the callback
  1. Control the Webchat widget:
  • The following table shows the Proto script that can be used to control the display of the widget:

Script

Description

Proto.show()

To make the UI visible.

Proto.hide()

To make the UI invisible.

Proto.openWindow()

To open the chat window.

Proto.closeWindow()

To close the chat window.

Proto.startNewChat()

To start a new chat.

❗️

Important

By default, the Webchat widget is set to hide. You must call Proto.show() explicitly to display the floating bubble or webchat on your website.

  • Here's an example to show the chatbot and open chat window after customer clicks
<html>
  <body>
    <button onclick="openChatbot()">Talk to bot</button>

    <script type="text/javascript" src="https://app.proto.cx/webchat/client.js"></script>
    <script>
      Proto.init({
        gwId: '<WEBCHAT-CHANNEL-ID>',
        env: ''
      });

      function openChatbot() {
        Proto.show();
        Proto.openChatWindow();
      }
    </script>
  </body>
</html>
  • Here's an example to toggle the Webchat with a button:
<html>
  <body>
    <div>
      <button onclick="toggle">Toggle</button>
    </div>

    <script>
      function toggle() {
        if (Proto.status.isVisible) {
          Proto.hide();
        } else {
          Proto.openChatWindow();
          Proto.show();
        }
      }

      Proto.init(
        {
          gwId: '<WEBCHAT-CHANNEL-ID>',
          env: ''
        },
        function() {
          Proto.hide();
        }
      );
    </script>
  </body>
</html>
  1. Set the Webchat default language:
  • Use Proto.setLanguage(langCode) to dynamically set the language (if the language dropdown selection is disabled)
  • The following table shows the supported langCode:

langCode

Language

af

Afrikaans

am

Amharic

ar

Arabic

bn

Bengali

zh_CN

Chinese (Simplified)

zh_TW

Chinese (Traditional)

nl

Dutch

en

English

fi

Finnish

fr

French

de

German

ha

Hausa

hi

Hindi

id

Indonesian

it

Italian

ja

Japanese

kn

Kannada

ms

Malay

no

Norwegian

ru

Russian

es

Spanish

sw

Swahili

sv

Swedish

tl

Tagalog

ta

Tamil

te

Telegu

th

Thai

tr

Turkish

vi

Vietnamese

  1. Reassign incoming chats to specific team:
  • Use Proto.forceTransferCurrentChat(ateamId) to automatically redirect chats to a specific team * You may find the ateamId in the team settings

🚧

Requirement

The ateamId must not be empty or null.

  1. Update preferred team:
  • Use Proto.setPreferredTeamId(ateamId) to dynamically set the preferred team
  • Current chats will not be transferred
  • New chats will be assigned to the preferred team by default

📘

Note

If ateamId is null, new chats will be directed by the chabot.

  1. Authenticate customers via the webchat:
  • Customers who exist in Humans are provided with a Unique ID

  • You can use this Unique ID to identify the customer who is using the Webchat

  • There are two ways to authenticate a customer.

    • First is to set the humanUid on Proto.init(options={}, callback=null)
    • Second is by using Proto.setHumanUid(humanUid)
  • Please refer to Authentication API

  1. Manually trigger a message on webchat:
  • Use Proto.sendTrigger(triggerCode) to manually trigger a trigger block message.

📘

Note

The triggerCode is the API code you defined in the trigger block.

  1. Set the Webchat Status Attributes:
  • Proto.status is an object representing the state of the Webchat
  • The following table shows the attributes of the webchat status

Field

Type

Description

isVisible

Boolean

true if the UI is visible; false if the UI is invisible.

isWindowOpened

Boolean

true if the chat window is open; false if the chat window is close.

currentChatId

String

The universally unique ID (UUID) of current chat.

  1. Set the Webchat Event Handlers:
  • You can define scripts to be automatically executed when an event occurs in the Webchat event handlers
  • The event handler will be triggered with an argument
  • The following table shows the supported events in Webchat

Event Name

Argument Type

Description

onConnect

ConnStatus

Webchat connected.

onReconnect

ConnStatus

Webchat reconnected.

onDisconnect

ConnStatus

Webchat disconnected.

onWindowOpened

ConnStatus

Chat window is opened.

onWindowClosed

ConnStatus

Chat window is closed.

onChatStarted

Chat

A new chat is started.

onTransferred

Chat

Current chat is transferred from bot to agent, of from one agent to another.

  • The following table shows the arguments of the event handlers:

Argument Type

Argument

ConnStatus

preferredTeamId

ConnStatus

anonId

Chat

anonId

Chat

chatId

Chat

ateamId

Chat

closed

  • Here's an example of webchat event handlers:
<html>
  <body>
    <script>
      Proto.onConnect = function(conn) {
        console.log('webchat connected');
      };
      Proto.onReconnect = function(conn) {
        console.log('webchat reconnected');
      };
      Proto.onChatStarted = function(chat) {
        console.log('chat ' + chat.id + ' started');
      };

      Proto.init(
        {
          gwId: '<WEBCHAT-CHANNEL-ID>',
          env: ''
        },
        function() {
          Proto.show();
        }
      );
    </script>
  </body>
</html>

What’s Next