Embeding in WebView with Channel

Overview

This guide explains how to integrate a webchat into a WebView component on mobile devices or on any web page without using the chat-ui-launcher script.

While the code examples in this guide use JavaScript in a browser environment, the principles, concepts, and methods described apply equally to both browser and WebView contexts. The core functionality and integration process remain the same regardless of the specific environment.

The webchat uses the PostMessage mechanism for communication between the web content and the hosting environment (native app or web page). This approach provides flexibility for developers who want more control over the webchat integration and communication process.

Mobile Integration

For mobile applications, this guide explains how to use the PostMessage mechanism to embed the webchat into a WebView component.

Web Page Integration

For web developers who prefer not to use the chat-ui-launcher script, this guide demonstrates how to embed the webchat directly into any web page using an iframe. This method requires manual handling of the PostMessage communication but offers greater customization and control.

In both scenarios, the PostMessage API ensures secure and efficient communication between the webchat and its hosting environment, whether it's a native mobile app or a web page.

PostMessage Mechanism in General

The PostMessage API allows secure communication between the webchat (running in the WebView) and the native app or website.

Sending Information to Webchat

To send information to the webchat, use the following format:

{
  "type": "EVENT_TYPE",
  "payload": {
    // Event-specific data
  }
}

Receiving Messages from Webchat

Set up event listeners in your native code or website to handle messages sent from the webchat.

window.addEventListener('message', (event) => {
   if(event.data.type === 'CLOSE_CONVERSATION_WINDOW'){
     // Handle the CLOSE_CONVERSATION_WINDOW event 
   }
})

Supported Events

Events to Send to Webchat

SET_CONFIG
Required to initialize the webchat.

{
  "session": {
    "id": "unique-session-identifier"
  },
  actionButtons: {
    conversationWindow: {minimize: false, resetAndMinimize: false}
  }
}

START_CONVERSATION
Starts a new conversation. No payload required.
CLOSE_CONVERSATION
Closes and resets the current conversation. No payload required.
DESTROY
Destroys the webchat and closes the conversation session. No payload required.

Events Received from Webchat

WEBCHAT_READY
Sent when the webchat is initialized and ready.
CLIENT_MESSAGE_SENT
Sent when a user sends a message.
MESSAGE_RECEIVED
Sent when the webchat receives a message from the bot.
CONVERSATION_END
Sent when the conversation is finished.
CLOSE_CONVERSATION_WINDOW
Sent when the user clicks the close (X) icon.
MINIMIZE_CONVERSATION_WINDOW
Sent when the user clicks the minimize icon.
DESTROY_DONE
Sent when the webchat is destroyed.

Implementation Steps

Embed the webchat in your environment (e.g., using an iframe in a web page).
Implement the PostMessage mechanism for two-way communication.
Generate and manage a unique session ID on the host side.
Listen for the WEBCHAT_READY event from the webchat.
Send the SET_CONFIG event to initialize the webchat, including the session ID.
Implement handlers for other events as needed.
Ensure proper session management throughout the lifecycle of your application.

Example Implementation

Below is a working example of a complete HTML file embedding the webchat. Note: this file must be served from localhost:8000 due to channel configuration.

<!DOCTYPE HTML>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">

  <style>
    iframe {
      height: calc(100vh - 4px);
      width: 100%;
      border: none;
    }
    body {
      margin: 0;
    }
  </style>
</head>

<body>

<script type="text/javascript">
  window.sentiOneChat.initWebChat({
    chatSrc: "https://webchat.app.chatbots.sentione.com/fullscreen",
    channelId: "dd301990-c156-4afb-b43e-f995c9a84a84",
  });
</script>

<iframe
  id="webchat-frame"
  src="https://webchat.app.chatbots.sentione.com/fullscreen/dd301990-c156-4afb-b43e-f995c9a84a84"
  title="WebChat">
</iframe>

<script>
  const iframe = document.getElementById('webchat-frame');
  const chatOrigin = "https://webchat.app.chatbots.sentione.com";

  const sendMessageToWebchat = (type, payload) => {
    iframe.contentWindow.postMessage({ type, payload }, chatOrigin);
  };

  function getOrCreateSessionId() {
    const key = 'webchat-session-id';
    let sessionId = localStorage.getItem(key);
    if (!sessionId) {
      sessionId = crypto.randomUUID();
      localStorage.setItem(key, sessionId);
    }
    return sessionId;
  }

  const sessionId = getOrCreateSessionId();

  iframe.addEventListener('load', () => {
    sendMessageToWebchat('SET_CONFIG', {
      session: {
        id: sessionId
      },
      actionButtons: {
        conversationWindow: {minimize: false, resetAndMinimize: false}
      }
    });
  });

  window.addEventListener('message', (event) => {
    if (event.origin !== chatOrigin) return;

    switch (event.data.type) {
      case 'WEBCHAT_READY':
        console.log('[WebChat] Ready');
        sendMessageToWebchat('START_CONVERSATION');
        break;
      case 'CLIENT_MESSAGE_SENT':
        console.log('[WebChat] Client message sent');
        break;
      case 'MESSAGE_RECEIVED':
        console.log('[WebChat] Message received');
        break;
      case 'CLOSE_CONVERSATION_WINDOW':
      case 'MINIMIZE_CONVERSATION_WINDOW':
      case 'DESTROY_DONE':
        console.log('[WebChat] Event:', event.data.type);
        break;
    }
  });
</script>

</body>
</html>

Important Note on Session Management

The "session" field, particularly its "id" subfield, is crucial for proper webchat functionality.
The session ID should be generated on the host side (your application or webpage).
It is the host's responsibility to store and manage this session ID.
The host should keep the session ID up to date and reset it when necessary (e.g., starting a new conversation, user logout).
Proper session management ensures conversation continuity and user experience consistency.

Troubleshooting

If PostMessage events are not being received, check that JavaScript is enabled in the WebView.
Verify that the correct URL is being loaded in the WebView.
Ensure that the PostMessage event listeners are set up correctly on both the native and web sides.

Remember to refer to the latest documentation for your specific webchat provider, as the exact implementation details may vary.