Webchat

Heres Webchat can be placed on client web properties, and used from mobile applications via a webview.

Below is a guide on how to integrate the Heres widget into any web page.

(function (H, e, r, es, B, o, t) {
       H["heres-widget"] = es;
       H[es] =H[es] || function () { (H[es].q = H[es].q || []).push(arguments);};
       (o = e.createElement(r)), (t = e.getElementsByTagName(r)[0]);
       o.id = es;H.heresAgent = B;
       o.src = "https://widgetv2.heres.ai/heres.js";
       o.async = 1;
       t.parentNode.insertBefore(o, t); 
})(window, document, "script", "heres", "NOMEAGENTE");

NOMEAGENTE is the name of the Heres agent, it is provided by Heres at the time of activation

To load the widget in testing version use o.src= “https://widgetv2.heres.ai/testing/heres.js”

The script asynchronously loads the script and prepares in the global namespace the heres function, which then becomes accessible via heres() or window.heres()

This function gives access to the widget API, specifically:

Initial configuration (configObject object)

Through the configObject object, parameters can be passed to the bot:

initialStep: initial step (to be agreed with conversational designers)

externalId: user id

startOpen: whether the chat should open by itself as soon as available

heresIsMobileApp: if the chat is used by a mobile app, then it should open automatically and it should not be possible to close it.

… other data agreed with conversational designers

Integrity:

It is an integrity field, necessary to prevent Client Side Tampering attacks, where the malicious user could modify the data on the page to gain access to unavailable information. It provides for coordinated server-side control of Heres, which enables validation of information, through a shared key (PEPPER).

It is calculated in this way:

1. The configObject is taken
2. The botId, startOpen, and integrity keys are removed, as well as all those whose names begin with heres (e.g., heresIsMobileApp); their values should not be counted for the integrity calculation.
3. Keys are sorted alphabetically
4. Values are extracted, and concatenated with “|”
5. SHA1 of the string PEPPER + “|” + values concatenated with “|” in hex format is calculated
6. The first 16 characters are taken
7. The integrity parameter is added to the configObject object.

For example, if the shared pepper is: Pb78432!ds

heres("init", {
    externalId: "matteo.ligabue@heres.ai",
    integrity: "d784db65429fb7f8"
})

Then the integrity will be calculated as:

integrity = sha1("Pb78432!ds|matteo.ligabue@heres.ai").substring(0,16)

// oppure usando il modulo built-in di node cryto
integrity = require("crypto")
  .createHash('sha1')
  .update("Pb78432!ds|matteo.ligabue@heres.ai")
  .digest('hex')
  .substring(0,16)

While in this other example:

heres("init", {
    externalId: "rebecca.barbanti@heres.ai",
    integrity: "795c290f5285bba2"
})

we will have:

integrity = sha1("Pb78432!ds|rebecca.barbanti@heres.ai").substring(0,16)

// oppure usando il modulo built-in di node cryto
integrity = require("crypto")
  .createHash('sha1')
  .update("Pb78432!ds|rebecca.barbanti@heres.ai")
  .digest('hex')
  .substring(0,16)

Please note: integrity is a function only of the pepper and the passed values, not of time, so it is possible to store the calculated values in a cache; if the script is invoked with the same extra parameters, the integrity value will always be the same.

Data Caching

Normally, parameters passed to the Heres chatbot via the heres( init’, {}) function are used for server-to-server API calls. Therefore, it is critical that such information (e.g., email) is passed to the script only in legitimate cases; we urge special attention to caching of such information, to avoid disclosure of confidential information between unrelated users.

Messages from chat (formerly dispatchEvent)

The chat can send to the events page, which are agreed upon together with Heres’ Conversational Design department.

These events consist of a name and a payload (a JavaScript object) and are sent directly to the browser’s window object.

window.addEventListener('message', function (message) {});

Such events can be captured by the page with code like this:

window.addEventListener('message', function (message) {
  if(message.data.type == "heres" ){
      // message.data.message contiene il nome del messaggio
      // message.data.payload contiene il payload del messaggio
  }
});

For those who had implemented the old Heres logic, simply call the function used in the previous implementation inside the new listener.

For example, if the function used in the old implementation had been called dispatchHeres(eventName, eventPayload) then just adding this snippet would be enough to ensure compatibility on these events:

window.addEventListener('message', function (message) {
  if(message.data.type == "heres" ){
      dispatchHeres(message.data.message, message.data.payload)
  }
});

New feature: Hide widget

Through the Heres console, in addition to being able to disable the bot, it is also possible to completely hide the widget from the site.

When that option is enabled, the script does nothing (it does not inject anything into the DOM of the page, does not activate any listener, etc…) In practice, calls to the heres() function do not result in anything.

Mobile App Integration

To integrate the webchat into a mobile app, the strategy is to use a webview.

The webview must contain the initialization script and the call to the init function.

It is possible to pass to the init function the heresIsMobileApp flag valued to true, this flag causes the chat to start open (as when the startOpen flag is passed) and some interface elements are different (mainly the chat close X does not appear and the menu item ‘Close chat’.

If you want to use full-screen chat, i.e., hiding the Heres header (perhaps because the app already includes headers or navigation tools outside the webview) you can insert the following snippet into the webview html code, which directly intervenes on the widget style to maximize the chat area.

<style>
.heres_chat_panel .heres_iframe {
    position: absolute;
    width: 100% !important;
    height: 100% !important;
    top: 0px !important;
    left: 0px !important;
    z-index: 1000 !important;
}
.heres_home_btn {
    z-index: 1020 !important;
}
.heres_composer_shield {
    z-index: 1010 !important;
}
</style>