PostMessage Events

This comprehensive guide provides detailed instructions on how to handle postMessage events to receive real-time events from Chat Data: chat, live-chat-escalation, lead-submission and minimize-widget. It covers what each event is about, and provides example code to help you seamlessly integrate and manage postMessage events on your website.

PostMessage Events

While both webhooks and postMessages can send events in real-time, there are some advantages unique to postMessages. For instance, because postMessages are sent directly from the chatbot to your website, they eliminate the need for network requests and allow your website to respond immediately based on each user's activity. For example, you can display your customer's name on your website after they have entered their name in the chatbot widget, which is impossible with webhooks.

Currently, four events are supported when you embed our chatbot as a widget bubble or an iframe on your website: chat, live-chat-escalation, minimize-widget, and lead-submission.

Events Payload

Let's examine each postMessage event one by one. The whole postMessage event looks like the following picture. For simplicity, we will just show the payload in the event.data when we describe each event.

Chat

All chat conducted in the chatbot will trigger a postMessage with the chat event type. Here is an example of the event's data payload

{
    "event": "chat",
    "payload": {
        "chatbot_id": "654aee418bc9a33b0e50d0ad",
        "chatbot_name": "Chat Data AI assistant",
        "chatbot_display_name": "Chat Data",
        "conversation_id": "5d4e7c46-4c54-4bb2-9bc8-170a3fc647e2",
        "message": "How to resell the chatbot with my own domain?",
        "source": "widget",
        "lead": {
            "uuid": "90e8c9cc-017e-4876-882d-19efd88b10ba",
            "name": "Customer",
            "email": "[email protected]",
            "source": "widget"
        }
    }
}

Live Chat Escalation

When the user clicked the live chat escalation button, a postMessage with the live-chat-escalation event type will be fired out.

{
    "event": "live-chat-escalation",
    "payload": {
        "chatbot_id": "654aee418bc9a33b0e50d0ad",
        "chatbot_name": "Chat Data AI assistant",
        "chatbot_display_name": "Chat Data",
        "conversation_id": "5d4e7c46-4c54-4bb2-9bc8-170a3fc647e2",
        "messages": [
            {
                "role": "assistant",
                "content": "👋 Hello there! I'm Chat Data AI, your go-to source about Chat Data!",
                "timestamp": "2024-08-24T06:10:29.077Z",
                "_id": "66c97975a5f5d4ceebebb86e"
            },
            ...
        ],
        "source": "widget",
        "lead": {
            "uuid": "90e8c9cc-017e-4876-882d-19efd88b10ba"
        }
    }
}

Lead Submission

The lead form submission will trigger a postMessage with the lead-submission event type.

{
    "event": "lead-submission",
    "payload": {
        "uuid": "90e8c9cc-017e-4876-882d-19efd88b10ba",
        "name": "Customer",
        "email": "[email protected]",
        "source": "widget"
    }
}

Minimize Widget

A click on the close icon on the chatbot will trigger a postMessage with the minimize-widget event type. The minimize-widget event doesn't have any payload. You can listen to this event to hide the chatbot if you embed the chatbot as an iframe directly in your own chatbot widget container.

How to handle PostMessage Events

The postMessage events are available in the Standard plan or above. Website owners can listen to these events on their website to respond accordingly.

React Example

Here's a detailed guide on how to implement this in React:

  const appUrl = 'https://www.chat-data.com';
  // This is the embedding domain of the chatbot. You should replace it if you use your own domain.
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      if (event.origin !== appUrl) {
        return;
      }

      const data = event.data;

      switch (data.event) {
        case 'chat':
          console.log('Received chat event:', data.payload);
          // Handle chat event
          break;
        case 'live-chat-escalation':
          console.log('Received live chat escalation:', data.payload);
          // Handle live chat escalation
          break;
        case 'minimize-widget':
          console.log('Minimizing widget');
          // Handle minimizing widget
          break;
        case 'lead-submission':
          console.log('Received lead submission:', data.payload);
          // Handle lead submission
          break;
        default:
          console.log('Unhandled event:', data.event);
      }
    };

    window.addEventListener('message', handleMessage);

    return () => {
      window.removeEventListener('message', handleMessage);
    };
  }, [appUrl]);

JavaScript Example

This is the example for the vanilla JavaScript.

    <script>
        (function() {
            var appUrl = 'https://www.chat-data.com'; 
            // This is the embedding domain of the chatbot. You should replace it if you use your own domain.
            function handleMessage(event) {
                if (event.origin !== appUrl) {
                    return;
                }

                var data = event.data;

                switch (data.event) {
                    case 'chat':
                        console.log('Received chat event:', data.payload);
                        // Handle chat event
                        break;
                    case 'live-chat-escalation':
                        console.log('Received live chat escalation:', data.payload);
                        // Handle live chat escalation
                        break;
                    case 'minimize-widget':
                        console.log('Minimizing widget');
                        // Handle minimizing widget
                        break;
                    case 'lead-submission':
                        console.log('Received lead submission:', data.payload);
                        // Handle lead submission
                        break;
                    default:
                        console.log('Unhandled event:', data.event);
                }
            }

            window.addEventListener('message', handleMessage);

            // Cleanup function (if needed)
            // window.removeEventListener('message', handleMessage);
        })();
    </script>

By listening to the postMessage events, you can respond to the user's actions in real-time on your website, for example, pop up designed for the user with his name, email, and the conversation history, enhancing the user experience and engagement on your website.