Skip to main content

Chat widget payload

A payload is used to pass the information to the bot.

Consider that you have a requirement to pass the data of the user who is using the chat widget. In such cases, you can use payload to pass data from your website to the bot. For example, payload passes the data such as account IDs, customer identifiers like names, email addresses, and phone numbers, or other metadata associated with a user from your website to the bot.

In the payload, you need to create a string that is a key-value pair consisting of data and its value (in lower case). The data must have string-to-string key-value pairs. Payload is passed in JSON format. An error is displayed when data other than key-value is passed in the JSON code.

payload security

Payload is securely passed in HTTPS post request to secure the information passed in it.

In this article, you will learn:

1. Pass values from the web client to the bot (chat widget v2)​

To pass values from your parent interface to the bot, you can make use of payload data, which needs to be configured in the bot script and init function.

1.1 Pass payload data via bot script​

To pass the payload data via script, paste the bot script at the end of the </body> tag

Following is a sample bot script:

<script type="text/javascript">
window.ymConfig = {"bot":"x1657623696077","host":"https://cloud.yellow.ai"};
(function() {
    var w = window,
        ic = w.YellowMessenger;
    if ("function" === typeof ic) ic("reattach_activator"), ic("update", ymConfig);
    else {
        var d = document,
            i = function() {
                i.c(arguments)
            };

        function l() {
            var e = d.createElement("script");
            e.type = "text/javascript", e.async = !0, e.src = "https://cdn.yellowmessenger.com/plugin/widget-v2/latest/dist/main.min.js";
            var t = d.getElementsByTagName("script")[0];
            t.parentNode.insertBefore(e, t)
        }
        i.q = [], i.c = function(e) {
            i.q.push(e)
        }, w.YellowMessenger = i, w.attachEvent ? w.attachEvent("onload", l) : w.addEventListener("load", l, !1)
    }
})(); 
</script>

Add the payload data in the following bot script:

<script type="text/javascript">
window.ymConfig = {"bot":"x1657623696077","host":"https://cloud.yellow.ai", "payload": {
                "name": "YellowDemo1",             // Add payload data here
                "phoneNumber": "08123546465",      // The values can be dynamic
                "email": "[email protected]",
            },};
(function() {
    var w = window,
        ic = w.YellowMessenger;
    if ("function" === typeof ic) ic("reattach_activator"), ic("update", ymConfig);
    else {
        var d = document,
            i = function() {
                i.c(arguments)
            };

        function l() {
            var e = d.createElement("script");
            e.type = "text/javascript", e.async = !0, e.src = "https://cdn.yellowmessenger.com/plugin/widget-v2/latest/dist/main.min.js";
            var t = d.getElementsByTagName("script")[0];
            t.parentNode.insertBefore(e, t)
        }
        i.q = [], i.c = function(e) {
            i.q.push(e)
        }, w.YellowMessenger = i, w.attachEvent ? w.attachEvent("onload", l) : w.addEventListener("load", l, !1)
    }
})(); 
</script>

The bot is initilized when the page loads. Once the bot loads, you can assign these values to variables using Variables node.

Variable format is {{{profile.payload.Your_Field_Name}}}

1.2 Pass payload data via init function​

You can also pass the payload data via the init function. If you want to reinitialize the bot with a new payload, you can use the below script:

	window.YellowMessengerPlugin.init({
		payload: {
			email: '[email protected]',
			member_id: '1231basd' // you can pass any info you want to be associated with the user based on your use case here. Note that this can be read by the bot using the {{profile.payload.member_id}} variable.
		}
	});

2. Pass values with chat widget v3​

Chat widget v3 is initialised with ChatWidget.init() instead of window.ymConfig, so the payload goes inside the yellowMessenger object. For the full v3 setup — install, every config option, and the available methods — see Chat widget v3 integration. Channels > Chat widget > Deploy gives you the base snippet; add payload to it:

<script type="text/javascript">
  (function () {
    var e = document.createElement("script");
    e.src = "https://cdn.yellowmessenger.com/plugin/widget-v3/prod/dist/loader.umd.js";
    e.async = !0;
    e.onload = function () {
      ChatWidget.init({
        yellowMessenger: {
          botId: "x1657623696077",
          host: "https://cloud.yellow.ai",
          payload: {
            name: "YellowDemo1",             // Add payload data here
            phoneNumber: "08123546465",      // The values can be dynamic
            email: "[email protected]"
          }
        }
      });
    };
    document.head.appendChild(e);
  })();
</script>

You read the values in the flow exactly as you do on v2 — {{{profile.payload.email}}}.

there is no re-init on v3

The payload is sent once, when the widget loads the session. ChatWidget.init() returns without doing anything if the widget is already on the page, so calling it a second time with a new payload has no effect — the v2 window.YellowMessengerPlugin.init() behaviour does not exist here.

To pick up a new payload (for example, after the user signs in), destroy the widget and initialise it again:

window.ChatWidget.destroy();
window.ChatWidget.init({
  yellowMessenger: {
    botId: "x1657623696077",
    host: "https://cloud.yellow.ai",
    payload: { email: "[email protected]", member_id: "1231basd" }
  }
});

This starts a new session — it is not an in-place payload update, and the earlier conversation is not carried over.

Last updated on