How to Transfer Custom Variables During a Subscription to a Chatbot

Integrating SendPulse with messengers allows you to transfer custom variables to your SendPulse account when someone subscribes via a widget or following a link. With the help of this functionality, you can pass values ​​for existing variables in the "Audience" tab of the chatbot.

Please note that to transfer variables, you need to create them in the "Audience" tab first. Data sent to non-existent fields will be disregarded.

You can also send UTM tags from your site or when subscribing via a link. The UTM tag values for each subscriber are stored in the corresponding variable in the "Audience" section.

If users subscribe to a chatbot using a widget or link, data transfer will only work for Facebook, Telegram, and Instagram chatbots. If users subscribe to WhatsApp chatbots, you cannot pass custom variables since social networks do not support this feature.

When Subscribing Via a Widget

The subscription widget’s JS script can automatically detect and save the UTM tags that were present during the current session when the site visitor subscribed. Therefore, in most cases, manual configuration is not required.

To pass UTM tags when subscribing to a widget, the URL link that leads to the site the user went to must have these parameters separated by & and ?.

If you want to pass other tags or additional variables, then you can use one of the two methods below.

Method 1. Using the window.oSpP Script

After adding the code of a Facebook chat widget, add the following code to the site:

<script type="text/javascript">
    window.oSpP = {
        phone: '+123123123',
        email: 'username@example.com',
        name: "Olga",
        city: "Odessa"
    }
</script>

If customers subscribed to the chatbot and after that the {{phone}}, {{email}}, {{city}} and {{name}} variables were added for these customers. Their data will not be transferred to the SendPulse account.

If you added a method for passing additional variables for web push notification subscribers using window.oSpP, there may be conflicts with the widget for collecting additional variables for the chatbot, and widget may not work.

Method 2. Using Hidden Input Fields

Add additional input fields with the sp_push_custom_data class to the site:

<input type="hidden" name="email" class="sp_push_custom_data " value="username@example.com">
<input type="hidden" name="phone" class="sp_push_custom_data " value="+123123123">
<input type="hidden" name="name" class="sp_push_custom_data " value="Olga">
<input type="hidden" name="city" class="sp_push_custom_data " value="Odessa">

Both methods are universal for sites on any CMS.

When Subscribing by Clicking on the Link

You can also pass variables when subscribing to a bot by inserting variables into the link to the bot via the ?ref (for Facebook and Instagram on Android) or ?start (for Telegram) parameter, separating the variables with the | sign. For Instagram and Facebook bots, you need to separate variables using __ sign.

Using this mechanism, you can transfer UTM-tags, email addresses, phone numbers, or other variables. When clicking on the link and starting the dialogue, the variable values are recorded for a specific subscriber in the chatbot audience.

You can copy a link example in the service. Read more: How to Launch a Bot via a Link or QR code.

For example, a Facebook chatbot link that passes additional variables will look like this: 

https://m.me/{page_id}?ref={flow_id}__var1_name=value1__var2_name=value2

Where flow_id is the flow ID, var_name is the variable's name, and value is the value to be passed. All given parameters in the example are optional.

A Facebook chatbot link that passes UTM tags will look like this: 

https://m.me/{page_id}?ref={flow_id}__utm_source=google__utm_medium=cpc

For the Telegram chatbot link, it is also necessary to add the intermediate domain "tg.pulse.is" because Telegram has a restriction on the format and size of the transmitted data. The link will look like this:

https://tg.pulse.is/{bot_name}?start={flow_id}|var1_name=value1|var2_name=value2

A Telegram chatbot link that transfers UTM tags will look like this:

https://tg.pulse.is/{bot_name}?start={flow_id}|utm_source=google|utm_medium=cpc

For Instagram chatbots, a link that passes additional variables will look like this:

https://ig.me/{bot_name}?ref=6394bea23fe17d63de57d6f3__var1_name=value1__var2_name=value2

For Viber chatbots, the link only works on devices with the app installed. The link will look like this:

viber://pa?chatURI=bot_name&context=flow_id|var1=value1|var2=value2

Last Updated: 28.04.2023