Identifying Web Bot Users

Every user that interacts with a bot on the Flow XO platform is associated with a unique identifier that is used any time Flow XO interacts with that user - either to send the user a message, set attributes in the users database record, etc. This unique identifier is called a "Response Path". The Response Path is like a phone number or e-mail address in that it uniquely identifies a Flow XO channel through which you can communicate with that user. The Response Path consists of two main pieces, the Bot ID and the Channel ID, and looks like this:

5852754509ac70000c104b80/c/n_QVIUyPr

The Bot ID is a unique identifier of the bot through which the user communicates with you. When you create a bot in the Bots section of Flow XO, perhaps to connect to a Facebook Page, a Telegram Bot or a Website, Flow XO will assign that Bot connection a unique Bot ID.

The Channel ID is the identifier assigned to a user by the channel the user is communicating on. For instance, if your bot is associated with a Facebook page, the Channel ID will be the "PSID" or "Page Scoped ID" - a unique ID associated with a specific Facebook user messaging on a specific page. For Telegram, the Channel ID might be the Telegram User ID for direct messages, or perhaps a Group ID or Channel ID if the user is communicating in a group or channel. If you have embedded your bot on a Webpage, however, the Channel ID a random ID generated when someone interacts with your chatbot for the first time. Unlike the Channel IDs from our other channels, where users are authenticated by the Channel Provider, on the web a users Channel ID will only remain the same on the same browser, on the same device, and the same session, meaning that if a user switches to incognito mode or clears their browser cache, the identify of the user is lost.

This is really the best that can be done for chatbots embedded on a webpage that can be accessed by anonymous (non-logged-in) users. Sometimes, though, you want to embed your bot on a page where you DO know who your users is because they have already authenticated with your website or web app. In this case, you want the identify of this user to remain stable across all browsers, devices and sessions, because they will authenticate with you and your website or app knows who they are in all these different situations.

When this is the case, there are two main ways you can tie a website user on your authenticated page to Flow XO's version of that user: using the External User ID feature, or by setting a custom Metadata field. Both of these must be set in Javascript when you embed the bot widget on your page, using our Web Messenger API.

External User ID

The most robust way to tie your user to a Flow XO user is to use the External User ID feature of our Web Messenger API. You simply set this configuration value when you embed the bot:

 function messengerReady() {    
        FxoMessenger.setConfig({
          externalUserId: 'User123',        
        });
}

 <script
      src="https://widget.flowxo.com/embed.js?callback=messengerReady"
      data-fxo-widget="{your embed code}"
      async
      defer
    ></script>

Of course, when you're embedding the widget into your own app or website, you won't hard-code the user identifier - you'll either need to inject it from a JavaScript variable if you have access to the User ID on the client side, or you'll need to inject it using your server side templating language, something like externalUserId: <%=myUserId%>.

When you embed the bot in this way, you'll notice that the User ID you see in the Flow XO user interface is no longer random, but matches the ID you provided:

Because the User ID / Channel ID is provided by you, you can easily construct a Response Path to communicate with that user. Using your interaction log, you can quickly find out your Bot ID:

Once you have the Bot ID, you can combine that with the User ID you provide, to construct a response path for the user in the format

{Bot ID}/c/{User ID}

So in the example above, the Response Path for User123 is:

5ec300d0fb2cc4008bdc28c3/c/User123

If you ever need your back end application (or even JavaScript on your web page) to fire off a Webhook to Flow XO that can send a message to this user, you can do it by simply sending your known User ID in the webhook data, and constructing a response path using the Bot ID you found in the interaction log:

The one downside to using a fixed External User ID is that the "Reset Conversation" button is no longer available. The reset feature relies on the auto-generated identities and can't be used when you provide a fixed User ID.

Sending User Info via Metadata

Another way you can pass user identify information to a flow on the web is through Metadata. Perhaps you have a webpage where users may sometimes be authenticated, and sometimes they might not. So you won't always have a User ID to set when configuring the widget. Or, perhaps you only have a JSON web token available that you want to pass to Flow XO to allow Flow XO to access your API on behalf of the current user, but obviously you don't want to use a JWT as a User ID.

Whatever the situation, you can also pass information to the Flow XO chatbot using metadata:

function messengerReady() {    
        FxoMessenger.setConfig({
          metadata: {
             myUserId: '123'
	  }       
        });
}

Now, the field 'myUserId' will be available on the Metadata of the trigger for any flow started by this instance of the web messenger. You can use this data in many ways, but a common one is to use it to make a call to a back end API and look up additional information about a user. 

Then it can be used anywhere, including an HTTP task like this:

Conclusion

Using either the externalUserId or the metadata feature when embedding the chatbot widget in your app or on your authenticated page will allow you to associate any given flow with a known user in your system. If all you need is to look up some information about that user, or access an API on behalf of your user, using metadata to pass in a user identifier or an authentication token might be sufficient.

However if your users are ALWAYS authenticated with your own back end, and you want to permanently associate your back end systems user identifier with a Flow XO user, to send them out-of-band messages through webhooks or for other reasons, the externalUserId feature is your best choice.

As always, please let us know if you have any questions or feedback,

Happy Flowing, 

Flow XO Support (support@flowxo.com)