Introduction

The purpose of this document is to explain how to use the HyperChat adapter for the Chatbot SDK and all the configuration options available. It also presents several practical examples.

Internal adapter

This adapter is included in the Chatbot SDK to facilitate the steps to integrate HyperChat and the escalation.

To use an internal adapter, you must set the adapters array like this:

adapters: [
   SDKHCAdapter.build(),
]

If this adapter meets your requirements, you can use it as explained above. If you need to modify its behaviour, see the "Customizing options" section below.

Configuration

Call the configure method with the required parameters to set up the configuration. You can find an explanation for each parameter in the "Configuration parameters" section below:

SDKHCAdapter.configure({
    apiKey: '<chat_api_key>',  // former "appId"
    region: '<chat_app_region>',
    room: function () {
        return '<roomId>';
    },
});

You must build the adapter in the adapters array inside the Chatbot SDK configuration:

var authorization = {
    domainKey:"<your_domain_key>",
    inbentaKey:"<your_API_key>",
};
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
    "adapters": [
        SDKHCAdapter.build(),
    ],
});

Configuration parameters

• apiKey (string) : The key of the HyperChat API (former "appId"). This defines the instance in which the chat opens.
• region (string) : The geographical region where the HyperChat app "lives". Valid values are: "eu" for Europe and "us" for the United States.
• room (function) : The room where the chat opens. This is mapped directly to a queue ID in the Benti App.
• surveyTimeout (number) : Number of milliseconds between the user successfully answers a survey and the chat closing the window and session. It is optional.

Example
To get the room from a query parameter where the current URL is www.currentweb.com?room=1, configure it like this:

room: function () {
    var queueID = SDKHCAdapter.helpers.getQueryParameterValue('room');
        return queueID;
}

• importBotHistory (Boolean) [optional] : Whether to import the chatbot previous conversation transcript to the chat or not. Defaults to false.
• setCookieOnDomain (Boolean) [optional] : Useful for multi-subdomain integrations. It defines whether HyperChat works in all the site (true) or just in the current subdomain (false). Defaults to false.
• setCookieSameSite (enum("None", "Strict", "Lax")) [optional] : Defines the SameSite cookie attribute. This setting allows to you to declare if Hyperchat cookie should be restricted to a first-party or same-site context. By default, no value is set.
• source (function) [optional]: The source ID for the chat (used to load FAQs for the agents, for example). Defaults to 3 (which in all instances corresponds to source Chat).
• lang (function) [optional]: Language code (in ISO 639-1 format) for the current chat. This is used when the engine checks if there are agents available for this language to assign the chat to one of them. Defaults to no language restriction. Note: this parameter is mandatory if the instance has languages.

Example
To get the user's configured browser language, configure it like this:

lang: function () {
    return SDKHCAdapter.helpers.getUserBrowserLanguage();
}

• fileUploadsActive (Boolean) [optional] : Defines if the user can see the file selector. If they can, they can send attachments. (Default value: false)
• extraInfo (function) [optional] : Extra information about the user context (or anything that might be useful for the agents to check). This is set as a chat user's "metadata". This information appears in the collapsible panel next to the chat window in the Benti App. (Default value: empty object)

Example
To capture the current URL (page from which the user opens the chat) and the text in an HTML element by its ID:

extraInfo: function () {
    return {
        url: SDKHCAdapter.helpers.getCurrentUrl(),
        property: SDKHCAdapter.helpers.getHTMLTagValueById('propertyId')
    }
}

• port (Number) [optional] : The service port to connect. Defaults to 8000. Possible ports are 8000 and 443.
• surveys (object) [optional] : Id of the Inbenta survey or url for an external survey.

Example
To use an Inbenta survey with id 2:

surveys: { 
     id: 2 
}

Example
To use an external survey URL:

surveys: { 
      url: 'https://www.external-url.com/aSurvey'
}

• transcript (object) [optional]: Configuration on downloading the chat conversation to PDF.

Example
To show the download button:

transcript: { 
     download: true
}

transcript.template (String) : Contains an alternative to the default template. The string must be an HTML fulfilling the Vue Template Syntax. The following properties are available:

• history: an Array with all the events of the chat. It has the same format as "History" in API definitions with the same content that the GET /chats/{chatId}/history endpoint returns.

• creator: an object containing id and name of the chat creator like { id: "<id>", name: "<name>" }.

  The following methods are available:

• $t: Formats a label using the vue-i18n Formatting.

• $d: Formats a date using the vue-i18n DateTime localization.

Example
Default template:

<div class="inbenta-bot__pdf" style="padding: 20px">
    <h1 class="inbenta-bot__pdf__title" style="font-family: Arial; font-size: 16px; color: #3d3f43; margin-bottom: 15px">{{ticketId}}</h1>
    <div class="inbenta-bot__pdf__body" v-for="entry in history" v-if="['messages:new', 'chats:join', 'chats:close', 'chats:create', 'chats:leave'].indexOf(entry.event) > -1">
        <div class="body__start-chat" style="padding: 10px; color: #3d3f43; font-size: 13px; font-family: Arial; font-style: italic; background-color: #EFF1F4; text-align: center; margin: 25px 0 15px; border-radius: 5px;" v-if="entry.event==='chats:create'">
            {{ $t('chatStarted', { date: $d(new Date(entry.created*1000), 'long') }) }}
        </div>
        <div class="body__messages" v-else style="padding: 14px 0; border-bottom: 1px solid #EFF1F4">
            <!-- show time -->
            <div class="body__messages__date" style="color: #8C8D8F; font-size: 12px; font-family: Arial; padding-bottom: 3px;">{{ $d(new Date(entry.created*1000), 'short') }}</div>
            <!-- messages:new case -->
            <div class="body__messages__message" v-if="entry.event === 'messages:new'">
                <div class="message__label" style="font-family: Arial; font-size: 12px; color: #3d3f43; font-weight: bold; padding-bottom: 3px;">{{entry.data.sender.nickname || entry.data.sender.name}}:</div>
                <div class="message__text" style="font-family: Arial; font-size: 14px; color: #3d3f43;" v-html="entry.data.message.message"></div>
            </div>
            <div class="body__messages__message body__messages__message--system" v-else-if="entry.event ==='chats:join'">
                <i style="font-family: Arial; font-size: 13px; color: #8C8D8F;">{{ $t('chatJoin', { name: entry.data.user.nickname || entry.data.user.name }) }}</i>
            </div>
            <div class="body__messages__message body__messages__message--system" v-else-if="entry.event ==='chats:leave'">
                <i style="font-family: Arial; font-size: 13px; color: #8C8D8F;">{{ $t('chatLeave', { name: entry.data.user.nickname || entry.data.user.name }) }}</i>
            </div>
            <div class="body__messages__message body__messages__message--system" v-else-if="entry.event ==='chats:close'">
                <i style="font-family: Arial; font-size: 13px; color: #8C8D8F;">{{ $t('chatClosed') }}</i>
            </div>
        </div>
    </div>
</div>

The template style can be customized by previously loading CSS styles into the page where the chat is taking place.

• transcript.methods (object): It contains functions that will be available in the custom template.

• transcript.labels (object): An object in the vue-i18n format for template labels in different languages.

• transcript.dateTimeFormats (object): An object in the vue-i18n DateTime localization format for date and time formats in different languages.

Example
Using all the possible properties:

transcript: {
    download: true,
    template: 'HTML',
    methods: {
        usefulFunction: () => {
            return 0;
        },
    },
    labels: {
        'en': {
            chatStarted: 'Chat started on {date}',
            chatJoin: '*** {name} joined the chat ***',
            chatLeave: '*** {name} left the chat ***',
            chatClosed: '*** Chat has been closed ***',
            customText: 'text' // also allows all the custom labels you might put in your customized template
        },
    },
    dateTimeFormats: {
        'en': {
            short: {
                hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false
            },
            long: {
                year: 'numeric', month: 'short', day: 'numeric',
                hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false
            }
        },
    }
}

• queue (object) [optional] : To toggle Queue mode, define the priority and queue position message update mode.

• singleQueuePositionMessage is available from version 1.38.0
• showEstimatedWaitingTime and shortWaitMessageCutoffTime are available from version 1.39.0

Example

queue: { 
    active: true, // (DEPRECATED AS OF v1.30.0 - DO NOT USE if you use v1.30.0 or older) Whether to set the queue mode active or not
    priority: function () { // Optional function to set the priority of the chat. Priority sets the "preference" of a user to be attended. Being 1 the highest priority. (i. e. a chat is created with priority 2, and later another with priority 1. Both are waiting. When a free slot is available, the chat with priority 1 will be released from the queue before the one with priority 2, even though it was created later).
        return 1;
    },
    singleQueuePositionMessage: true, // (default: true) If true, every time the queue position is updated, the message is updated. The queue position message will be appended as a new message if this parameter is set to false
    showEstimatedWaitingTime: true, // (default: false) If true, it displays users the estimated waiting time until they are attended by an agent. Check the "labels" section to know which labels are available for messages customization
    shortWaitMessageCutoffTime: 60, // (default: 60 seconds) Time from which "you'll be attended shortly" or the exact time will be shown
}

• keepConversationAfterSurvey (Boolean) [optional] : Avoid closing the chat window and restoring the chat session keeping the conversation once survey is submitted. Defaults to true.
• userMessageNotifications (object) [optional] : Play a sound when the end-user (web user) has not the browser tab focused and receives a message. The "source" property should be a valid URL where the sound file is stored. This setting is available from version 1.60.0.

Example

userMessageNotifications: { 
    active: true,
    source: 'https://freesound.org/data/previews/171/171671_2437358-lq.mp3', 
}

• notificationMessages (object) [optional] : Configures client-side browser notifications that inform the user about new messages received from chat agents.

Example

notificationMessages: {
   configured: true,
   titleMessage: 'title text',
   bodyMessage: 'body text',
   icon: 'https://www.inbenta.pro/backstage/images/notification-chat-big.png',
}

• notificationMessages.configured (boolean) : To define whether or not notifications should be sent to the user.

• notificationMessages.titleMessage (string) [optional] : To define the title of the notification.

• notificationMessages.bodyMessage (string) [optional] : To define the message body of the notification.

• notificationMessages.bodyMessage (string) [optional] : To add an icon to the notification.

• continueInQueueRequest (object) [optional] : Request the user to confirm whether they want to keep waiting for a chat agent or leave the queue. If the user remains inactive, this is considered a confirmation to leave the queue. The message can only be shown in browsers that support these notifications and if the user allows notifications on the webpage where the SDK is integrated.

Example

continueInQueueRequest: {
   requestIntervalTime: 3,
   timeToAnswerRequest: 10,
}

• continueInQueueRequest.requestIntervalTime (number) : The waiting time in minutes after which the confirmation request should be sent to users in the queue or sent again to users that have previously confirmed that they want to keep waiting.
• continueInQueueRequest.timeToAnswerRequest (number) : The time in seconds that the user has to answer the confirmation request before they are considered inactive and the chat closes automatically.
• adviceConnectionStatus (boolean) [optional] : Shows connection status updates to users when they lose the connection to the HyperChat or when the connection is restored.
• messageCharacterLimit (number) [optional] : This parameter contains the maximum number of characters that can be sent by a user in a single message in a HyperChat conversation. This limit does not apply to chatbot queries, but by default it has the same value as the limit defined for chatbot conversations.

Event subscription

The HyperChat adapter triggers events when certain actions happen in a chat. The events are the following:

• chat:created: Triggered when the chat is created.

  { chat }

• chat:closed: Triggered when the chat is closed.

  { chatId, 
    userId,
    reason // Optional String with the reason for closing the chat if it was not closed manually by a user. It can be "inactivity" if the chat was closed due to no activity in the chat, "forever:alone" if there were no agents to attend the chat, or "allAgentsDisconnected" if the chat was waiting in a queue and all the agents online in this queue then disconnected.
  }

• user:joined: Triggered when a user joins the chat.

  {
    chat, // Object with chat properties
    mode, // String 'watch' or empty otherwise
    sender, // String with the sender id
    transfer, // Boolean stating whether the join is from a transfer or not
    user // Object with the user properties
  }

• user:left: Triggered when a user leaves the chat.

  { chatId, userId }

• ticket:created Triggered when a chat is converted to ticket.

  {
    ticketId, // String with the ticket id in the form PROJECT-ID
    rawTicketId, // String with the ticket id in the form ID
    chat: {
      attended // Boolean stating if the chat was attended
    },
  }

• forever:alone: Triggered when there aren't any agents available for a chat.

  { chatId }

• expiry:alert: Triggered when the chat is about to expire due to inactivity. Whether to activate or not this feature and the time left for the event to trigger can be configured in Benti > Settings > Chat.

  { chatId,
    timeLeft // Time left in seconds before the chat closes
  }

• hyperChatAdapterError: Triggered when an error happens in the Adapter. The error is captured and this event triggered, but the execution is not stopped.

  [
    errorObject, // object
    extraInfo // string. More information about the error
  ]

• hyperChatAdapterInfo: Triggered when an event happens in the Adapter. It returns the event name and the data provided by each event.

  { 
    eventName, // string 
    data // object 
  }

  • agentsOnline: Triggered once agents online status is checked by the SDK.

  { 
    eventName: 'agentsOnline',
    data: {
      agentsOnline // boolean
    }
  }

It is easy to subscribe to these events. Here is an example:

// Function called when chatbot script is loaded
function buildUI () {
    // ...
    // SDKHCAdapter.configure and SDKHCAdapter.build
    // ...
    SDKHCAdapter.events.on('chat:created', (data) => {
        console.log('created', data);
    })
    SDKHCAdapter.events.on('chat:closed', (data) => {
        console.log('closed', data);
    })
    SDKHCAdapter.events.on('user:joined', (data) => {
        console.log('joined', data);
    })
    SDKHCAdapter.events.on('user:left', (data) => {
        console.log('left', data);
    })
    SDKHCAdapter.events.on('ticket:created', (data) => {
        console.log('ticket', data);
    })
    SDKHCAdapter.events.on('hyperChatAdapterError', (err, info) => {
        console.error(error, info);
    })
    SDKHCAdapter.events.on('hyperChatAdapterInfo', (info) => {
        console.error(info);
    })

}

Event subscription objects

• chat

  { 
  id, // String
  room // String
  creator // String with the creator user id
  source // Integer
  lang // String with the ISO 639-1 Code
  closed, // falsy value or a Unix timestamp of when the chat was closed
  users, // Array with users in the chat
  lastActivity, // Unix timestamp
  inQueue: Boolean
  }

• user

  { 
  id, // String
  name, // String
  nickname, // String
  providerId, // usually the instance user id
  gender // "N/A", "male" or "female"
  }

Helper functions

• setRoomFunction: Sets the function that determines the room where the chat will be created. Can be called anytime, for example just before the chat escalation.

SDKHCAdapter.setRoomFunction(function () {
    return 1; // Chat will be created in room 1
});

• resetAdapter: Clears all data stored by the adapter and leaves it ready to open a new chat from scratch.

  SDKHCAdapter.resetAdapter();

Labels

The HyperChat adapter uses labels defined in the chatbot sdk. These labels can be replaced and customized just like the other chatbot sdk labels:

Customizing options

This internal adapter works for the majority of cases and can be configured to perform more advanced operations. However, if you need to change its default logic for a truly custom solution, you can override this internal adapter with your own implementation.

To help you in this, the source code is available on GitHub at https://github.com/inbenta-products/hyperchat-bot-adapter. Feel free to take this code and modify it according to your specific needs.