Webchat API

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">
      window.ProtoSettings = {
        gwId: '<WEBCHAT-CHANNEL-ID>',
        env: '',
        onLoad: function() { Proto.show(); }
      };

      var d=document,s=d.createElement("script");
      s.type="text/javascript",s.async=true,s.src="https://app.proto.cx/webchat/client.js";
      var t=d.getElementsByTagName("script")[0];
      t.parentNode.insertBefore(s,t);
      s.addEventListener("load", function() {
        var p = window.ProtoSettings; Proto.init(p, p.onLoad);
      });
    </script>
  </body>
</html>

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

Methods

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 ProtoSettings field

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

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>

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

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.

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.

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 window.ProtoSettings{}
- Second is by using Proto.setHumanUid(humanUid)
Please refer to Authentication API

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.

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.

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>

Webchat API

Deploy snippet

📘
Note

Methods

📘
Note

❗️
Important

🚧
Requirement

📘
Note

📘
Note

Deploy snippet

📘Note

Methods

📘Note

❗️Important

🚧Requirement

📘Note

📘Note

📘
Note

📘
Note

❗️
Important

🚧
Requirement

📘
Note

📘
Note