Hyperchat Adapter

Introduction

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: [
   SDKHCAdapter.build(),
]

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.

Configuration parameters

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({
    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 = {
    domainKey:"<your_domain_key>",
    inbentaKey:"<your_API_key>",
};
InbentaChatbotSDK.buildWithDomainCredentials(authorization, {
    "adapters": [
        SDKHCAdapter.build(),
    ],
});

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 Backstage queue ID.

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

  • source (function) [optional]: The Backstage source ID for the chat (which is 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.

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 will be shown in the collapsible panel next to the chat window in Backstage. (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)
  • 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.

Example
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>
    <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>
        <span v-else-if="entry.event ==='chats:join'">
            <i>{{ $t('chatJoin', { name: entry.data.user.name }) }}</i>
        </span>
        <span v-else-if="entry.event ==='chats:close'">
            <i>{{ $t('chatClosed') }}</i>
        </span>
    </div>
    <div style="margin-top: 10px; margin-bottom: 10px; border: 1px solid black"></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': {
            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
            }
        },
    }
}

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
    }

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
});

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.