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
FieldTypeRequiredDescription
gwIdstringCompulsory Webchat Channel ID that can be found in Webchat > Settings page.
envstringOptionalTo be leave as empty string "" (default).
langstringOptionalThe language code of the webchat UI. The Master language of the bot is the default language.
ateamIdstringOptionalThe preferred team to accept new incoming chat. It this field is empty, bot will handle the chat.
humanUidstringOptionalThe 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:
ScriptDescription
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:
langCodeLanguage
afAfrikaans
amAmharic
arArabic
bnBengali
zh_CNChinese (Simplified)
zh_TWChinese (Traditional)
nlDutch
enEnglish
fiFinnish
frFrench
deGerman
haHausa
hiHindi
idIndonesian
itItalian
jaJapanese
knKannada
msMalay
noNorwegian
ruRussian
esSpanish
swSwahili
svSwedish
tlTagalog
taTamil
teTelegu
thThai
trTurkish
viVietnamese
  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
FieldTypeDescription
isVisibleBooleantrue if the UI is visible; false if the UI is invisible.
isWindowOpenedBooleantrue if the chat window is open; false if the chat window is close.
currentChatIdStringThe 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 NameArgument TypeDescription
onConnectConnStatusWebchat connected.
onReconnectConnStatusWebchat reconnected.
onDisconnectConnStatusWebchat disconnected.
onWindowOpenedConnStatusChat window is opened.
onWindowClosedConnStatusChat window is closed.
onChatStartedChatA new chat is started.
onTransferredChatCurrent chat is transferred from bot to agent, of from one agent to another.
  • The following table shows the arguments of the event handlers:
Argument TypeArgument
ConnStatuspreferredTeamId
ConnStatusanonId
ChatanonId
ChatchatId
ChatateamId
Chatclosed
  • 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