Events

The loader passes what happens in the chat to the page as browser events, so you can send them to your own analytics.

Listening for events#

The loader dispatches a CustomEvent named hfx:event on window. Its detail has two fields:

FieldTypeMeaning
detail.namestringThe event name, from the tables below.
detail.payloadobject, may be missingDetails for that event.
JS
window.addEventListener("hfx:event", function (e) {
  console.log(e.detail.name, e.detail.payload);
});

Add the listener anywhere on the page. Events only start once the chat has loaded, which is after the loader script has run.

Booking assistant events#

NameWhen it firesPayload
chat_openedThe chat has loaded and shown its greeting. In bubble mode the chat loads with the page, so this fires on page load, not when the guest clicks the button.{ destinationId }
chat_opened (resumed)The guest reloaded the page and their earlier conversation was restored.{ destinationId, resumed: true }
quote_shownThe assistant showed the guest a price card for a stay. Fires again when the price changes, for example after adding an extra.{ total: { amount, currency } }
checkout_startedThe guest chose to book and the payment step opened.{}

amount is in the currency's minor unit, so { amount: 34200, currency: "GBP" } is £342.00. currency is an ISO 4217 code.

Activity widget events#

Sent by the activity booking widget.

NameWhen it firesPayload
widget_loadedThe widget is ready to use.{ destinationId, numActivities }
slot_selectedThe guest picked a time slot.{ activityId, slotStart }
checkout_startedThe guest chose to book the slot.{ activityId, slotStart }
checkout_succeededPayment went through and the booking was made.{ bookingRef }
checkout_failedThe booking couldn't be started or the payment failed.{ reason }

Event names may grow. We may add new event names. Ignore names you don't recognise rather than treating them as errors.

Google Analytics 4#

With the Google tag (gtag.js) already on the page:

JS
window.addEventListener("hfx:event", function (e) {
  var name = e.detail.name;
  var p = e.detail.payload || {};
  var params = {};
  if (p.total) {
    params.value = p.total.amount / 100;
    params.currency = p.total.currency;
  }
  if (p.resumed) params.resumed = true;
  gtag("event", "chat_" + name, params);
});

The chat_ prefix keeps these events apart from your own. Mark chat_checkout_started as a key event if you want to count it as a conversion.

Google Tag Manager#

Push each event to the data layer, then build triggers on the chat_event custom event in Tag Manager:

JS
window.dataLayer = window.dataLayer || [];
window.addEventListener("hfx:event", function (e) {
  window.dataLayer.push({
    event: "chat_event",
    chat_event_name: e.detail.name,
    chat_event_payload: e.detail.payload || {}
  });
});

The postMessage protocol#

The chat runs in an iframe and talks to the loader with window.postMessage. The loader handles all of this for you. We document it so your security team can review exactly what crosses between the page and the chat. Embed the chat with the loader rather than building your own iframe: the protocol can change between versions, and the loader always matches it.

Every message is an object with a type starting hfx:. The current protocol version is 1.0, sent in hfx:ready.

From the chat to the page#

TypeFieldsWhat the loader does
hfx:readyversionReplies with hfx:init.
hfx:resizeheight (pixels)Inline mode: sets the height, between 320 and 900 pixels.
hfx:request-openNoneOpens the chat.
hfx:request-closeNoneCloses the chat.
hfx:expandmode: bubble or panelBubble mode: switches the panel between 400 by 640 and 460 by 760 pixels.
hfx:teasertextUses the text as the teaser, unless you set data-launcher-label.
hfx:eventname, payloadDispatches the hfx:event browser event described above.

From the page to the chat#

TypeFieldsMeaning
hfx:initparentOrigin, pageUrlThe page's origin and address.
hfx:openedNoneThe chat was opened.
hfx:closedNoneThe chat was closed.

Origin checks#

  • The loader only accepts messages from the chat's own origin, and only from its own iframe.
  • The loader only posts to the chat's origin, never to *.
  • The chat only accepts messages from the page origin it was given when it loaded. After hfx:init it ignores messages from any other origin, and it never posts to *.
Book a 20-minute call