Embeding in WebView

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 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.

Sending Information to Webchat

To send an 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 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.

  {
    "projectId": "your-project-id",
    "session": {
      "id": "unique-session-identifier"
    },
    "actionButtons": {
      "conversationWindow": {"minimize": 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 close 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.

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.

Web example

This is the example of embedding the webchat into a web page using an iframe, and handling the PostMessage communication manually.

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

    <style>
        iframe {
          height: calc(100vh - 4px);
          width: 100%;
        }

        body {
          margin: 0;
        }
    </style>
</head>

<body>

<iframe
    src="https://webchat.app.chatbots.sentione.com/fullscreen"
    title=""
    width="528"
    height="595">
</iframe>

<script>
  const iframe = document.querySelector('iframe');
  const chatSrc = 'https://webchat.app.chatbots.sentione.com/fullscreen'

  const sendMessageToWebchat = (type, payload) => {
    const iframe = document.querySelector('iframe');
    iframe.contentWindow.postMessage({"type": type, payload}, chatSrc)
  }

  window.addEventListener('message', (event) => {
    if(event.data.type === 'CLOSE_CONVERSATION_WINDOW'){
      console.log('Reveived event: ', event.data.type)
    }

    if(event.data.type === 'WEBCHAT_READY'){
      console.log('Reveived event: ', event.data.type)
    }

    if(event.data.type === 'CLIENT_MESSAGE_SENT'){
      console.log('Reveived event: ', event.data.type)
    }

    if(event.data.type === 'MESSAGE_RECEIVED'){
      console.log('Reveived event: ', event.data)
    }

    if(event.data.type === 'CONVERSATION_END'){
      console.log('Reveived event: ', event.data.type)
    }

    if(event.data.type === 'MINIMIZE_CONVERSATION_WINDOW'){
      console.log('Reveived event: ', event.data.type)
    }

    if(event.data.type === 'DESTROY_DONE'){
      console.log('Reveived event: ', event.data.type)
    }

    if (event.data.type === "WEBCHAT_READY") {
      sendMessageToWebchat('START_CONVERSATION')
    }
  })

  iframe.addEventListener('load', () => {
    const initConfig = {"projectId": "406c6ba1-22c5-4582-8bf6-0f05ac93c995",
      "appearance": {
        "headerTitle": "[TEST] Chat UI Launcher",
        "endOfConversationLabel": 'Conversation Ended'
      },
      "actionButtons": {
        "conversationWindow": {"minimize": true, "resetAndMinimize": true},
      },
      "session": {
        "id": "generated-by-host-session-id",
        "hostSessionCookie": true
      },
    }
    sendMessageToWebchat('SET_CONFIG', initConfig)
  })

</script>
</body>
</html>