Hyperchat Adapter


This document explains how to use the Hyperchat adapter for the Chatbot SDK, along with all the configuration options available and some 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: [

Note: The SDK at the beginning of the function name is what forces the SDK to use the internal adapter.

Caution: If you use the internal adapter, you must override every instance of HCAdapter with SDKHCAdapter, not only in the build, but also in the configuration.

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.


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:

    appId: '<chat_app_id>',
    region: '<chat_app_region>',
    room: function () {
        return '<roomId>';

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

var authorization = {
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
    "adapters": [

Configuration parameters

  • appId (string) : The ID of the HyperChat app. 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 Case Management App.

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 will work in all the site (true) or just in the current subdomain (false). Defaults to false.

  • 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.

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 Case Management App. (Default value: empty object)

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.

To use an Inbenta survey with id 2:

surveys: { 
     id: 2 

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.

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)
  • creator (an object containing id and name of the chat creator).

    The following methods are available:

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

Default template:

<div style="margin: 20px">
<h1 style="margin-top: 20px; margin-bottom: 20px;">{{ticketId}}</h1>
<div v-for="entry in history" v-if="['messages:new', 'chats:join', 'chats:close', 'chats:create'].indexOf(entry.event) > -1">
    <div v-if="entry.event==='chats:create'">
        {{ $t('chatStarted', { date: $d(new Date(entry.created*1000), 'long') }) }}
    <div v-else>
        <!-- show time -->
        <span>({{ $d(new Date(entry.created*1000), 'short') }})</span>
        <!-- messages:new case -->
        <span v-if="entry.event === 'messages:new'">
            <b>{{entry.data.sender.name}}</b>: {{entry.data.message.message}}
        <span v-else-if="entry.event ==='chats:join'">
            <i>{{ $t('chatJoin', { name: entry.data.user.name }) }}</i>
        <span v-else-if="entry.event ==='chats:close'">
            <i>{{ $t('chatClosed') }}</i>
    <div style="margin-top: 10px; margin-bottom: 10px; border: 1px solid black"></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.

Using all the possible properties:

transcript: {
    download: true,
    template: 'HTML',
    methods: {
        usefulFunction: () => {
            return 0;
    labels: {
        'en': {
            customText: 'text'
    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 and define the priority.

Important! This configuration is only available from the Chatbot SDK version 1.25.0 onwards.

  • From version 1.25.0 until 1.29.0 (both included), you have to have both the configuration in your Hyperchat instance and this one active for the queue mode to work.
  • From version 1.30.0 onwards, the "active" configuration in the adapter is not needed anymore. If the configuration in your Hyperchat instance is active, the queue mode will be active, which makes it easier to set up.
    More info here


queue: { 
    active: true, // (Deprecated from version 1.30.0) Whether to set the queue mode active or not
    priority: function () { // Optional function to set the priority of the chat
        return 1;

Event subscription

The HyperChat adapter will trigger 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 }
  • 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 CM > Settings > Chat.

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

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

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

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.
HCAdapter.setRoomFunction(function () {
    return 1; // Chat will be created in room 1


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

label text description variables
chat-ticket {ticketId} Showed when the ticket ID is received after the chat is closed ticketId: The ticket identifier.
queue-estimation-first You are the first in the queue. Showed when nobody else is in front of the user in the queue. queuePosition: The number of people in front of the user in the queue.
queue-estimation-second There is {queuePosition} person ahead of you. Showed when there is one person in front of the user in the queue. queuePosition: The number of people in front of the user in the queue.
queue-estimation There are {queuePosition} people ahead of you. Showed when there are more than one person in front of the user in the queue. queuePosition: The number of people in front of the user in the queue.

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.

Inbenta does not give any support for this code. It was open-sourced as an example.