An HTML Panel allows you to place an HTML document in an iframe in your chats, just above the entry box. Using HTML Panels, you can extend TalkJS UIs to have anything from credit card payments to lead collection forms, or, for instance, to show the product details of a marketplace transaction between your users.

Usage

HTML panels can be created for all UI options by simply making a createHtmlPanel call on the UI element. This call accepts a few parameters like height of the panel, allowing to customize the experience further. All options can be found here: JS SDK API.

The JS SDK also makes interacting with your HTML panels easy by passing you the window element of the requested URL in a promise when createHtmlPanel is called. But because of browser's security restrictions, when you try to access a panel's window variable, it's subject to the same-origin policy. This means that if you are on another domain, most of the properties of window will not be accessible. In this case, cross-domain communication can still be achieved with window.postMessage().

Note: We recommend that you host this HTML document on the same domain (and subdomain) as your main site. This is because browsers have a security feature called the Same-Origin Policy which severely limits the kind of programmatic interaction you can do with iframes hosted on different domains. Some of the example code below, for instance, will only work if you have both your main app and the embedded HTML document hosted on the same domain (https://www.mywebsite.com).

// Create a UI element like shown in previous examples
var inbox = talkSession.createInbox();
inbox.mount(document.getElementById("inbox-container"));

// Then call `createHtmlPanel`, which returns a Promise that's resolved with control methods
inbox.createHtmlPanel({
    url: "register-form.html", // or the absolute path: "https://www.mywebsite.com/frames/register-form.html"
    height: 300,
    show: true
});

When the panel is ready

The HTML Panel object exposes some promises that reflect the lifecycle of the window. You can use these to e.g. attach event handlers to controls inside the HTML panel.

inbox.createHtmlPanel({
    url: "register-form.html", // or the absolute path "https://www.mywebsite.com/frames/register-form.html"
    height: 300,
    show: true
})
.then(function(htmlPanel) {
    htmlPanel.DOMContentLoadedPromise.then(function() {
      // ... do work that includes manipulation of the DOM.
      var form = htmlPanel.window.document.getElementById("registration-form");
      form.submit();
    });
    htmlPanel.windowLoadedPromise.then(function () {
      // ... do work that requires all assets (including images, css, scripts, etc) of the HTML Panel to be fully loaded.
    });
});

Visibility

You can hide or show the HTML panel at any time. This is helpful when you want to preload the page or build interactive experiences.

htmlPanel.show();
htmlPanel.hide();

You can also use htmlPanel.isVisible(); to check the visibility of your panel.

If you want to be able to toggle the panel, write a function like below:

function togglePanel(htmlPanel) {
  if (htmlPanel.isVisible()) {
    htmlPanel.hide();
  } else {
    htmlPanel.show();
  }
}

registerForm.then(function(htmlPanel) {
  togglePanel(htmlPanel);
});

Resizing the panel

You can also set the height of the panel either when creating it with createHtmlPanel or by using htmlPanel.setHeight(). You should always pass a number, which is then interpreted as pixels.

registerForm.then(function (htmlPanel) {
  htmlPanel.setHeight(400); // Changes HtmlPanel height to 400px
});

Different HTML Panels for different conversations

By default, an HTML Panel is shown for all conversations, even if the user switches to a different conversation (by clicking in the feed in the Inbox, or when the select method is called).

But you can also limit an HTML Panel to a single conversation. This means that the panel will be shown only when that conversation is displayed:

inbox.createHtmlPanel({
    url: "https://www.mywebsite.com/frames/register-form.html",
    height: 300,
    show: true,
    conversation: myConversation // <-- that's the one
})

conversation can be either a string ID or a conversation object as returned by getOrCreateConversation.

You can call createHtmlPanel multiple times this way, to immediately load multiple panels, for different conversations. TalkJS will preload every HTML Panel you create, but keep them hidden until the appropriate conversation is selected.

If you omit conversation in one createHtmlPanel call but not in others, then the panel without a given conversation will act as the default HTML Panel. It will be shown for conversations that have no conversation-specific HTML Panel configured.

HTML Panel Limitations

Due to browser security policies that are impossible to circumvent, your HTML Panels must be hosted on HTTPS. This means that:

  • If it is not possible for you to host the HTML Panel content on HTTPS, then you cannot use HTML Panels.
  • As described above, to be able to interact with the HTML Panel client-side with JavaScript, it needs to be on the "same origin". Browsers consider http://example.com and https://example.com to be different origins, so means that your entire app needs to be hosted on HTTPS if you need this.
  • You also need to host the HTML Panel content on HTTPS during development, which can be a bit cumbersome.

One effective way to make developing and testing HTML Panels less cumbersome is to use a tool like ngrok. Ngrok lets you serve the HTML Panel pages from your local development server over HTTPS, by giving it a special custom URL such as https://qwerty12345.ngrok.io which points straight to your local development server. The free version is usually more than capable enough for this.

Read more

  • Learn about all options you can pass as options for HTML panels here.
  • Learn about methods for HtmlPanel instances here.
  • More about the Same-Origin Policy on MDN (Mozilla Developer Network)