Push attributes for a known user in the chatbot via the API

When your users are logged-in, you may want to push information about them into the chatbot in order to provide a better conversational experience.
For example, providing your user plan-level to the chatbot could help avoiding asking questions, and lead faster to the adequate answer.

Clustaar enables you to store information in two ways :

• using the interlocutor session
• using interlocutors attributes

The main difference between those 2 options is the lifetime of the information stored.
The session usually lasts the duration of a story, while the interlocutors attributes are permanent.
Even if the interlocutor comes back a few weeks later, the information stored will still be there.

This guide focuses on the push of user attributes via the API; if you want information about the session you can read the dedicated documentation.

📘

Wanna push attributes from your website?

If you don't want to push attributes from the API, but directly in JavaScript from your website, please refer to our JavaScript SDK.

Setting the attributes

First you need an interlocutor, so let's create one.

The request below will create an empty interlocutor for your user that has the 25631 ID in your own database (replace {BOT_ID} and {ACCESS_TOKEN} with your own information) :

curl -d '{"type": "interlocutor", "userID": "25631"}' \
    -X POST https://api.clustaar.io/bots/{BOT_ID}/interlocutors/clustaar_web_chat \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'

The response now contains your interlocutor for your user with the ID 25631 :

{
  "data":{
    "type":"interlocutor",
    "id":"5a82df51bf8a1100a0615f4a"
  }
}

Once the interlocutor is created if you want to update some attributes you can use the update interlocutor endpoint in order to set some of its attributes :

curl -d '{"type": "interlocutor", "userID": "25631", "firstName": "John", "customAttributes": {"age": "30"}}' \
    -X PUT https://api.clustaar.io/interlocutors/5a82df51bf8a1100a0615f4a \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'

This will set the first_name attribute to John and a custom attribute called age to 30.

Using the attributes

If you want to use the attributes in your bot you can use the @user.ATTRIBUTE syntax to echo those attributes.

For example if you have stored a first_name attribute on your interlocutor you could welcome this person with a text message containing :

Hello {{ @user.first_name }} !

This will send "Hello John !" for the interlocutor you just created.

Don't forget you can provide a default value while echoing a value in order to prevent empty messages :

Hello {{ @user.first_name || "there"}} !

This will send "Hello there !" if the first_name attribute is empty for the current interlocutor.

Setting up the userID in your webchat

Finally if you use our webchat, you will have to set the userID that should be used by the webchat to talk to your bot.

This is done by setting the userID attribute of the clustaarSettings variable.
Below you can see an example of the generated configuration if your currently logged in user has an ID of 25631 :

<script>
    window.clustaarSettings = {
      bot_id: '5a53754ba09795000bbd72a6',
      bot_token: 'xxxxxxxxxxxxxxxxxxxxxx',
      welcomeMessage: 'Hi, this is a conversation with a bot assistant, feel free to ask him whatever you want !', //optional
      widgetTitle: 'Need help?',
      promptPlaceholder: 'Your question',
      closeButtonLabel: 'Close',
      userID: '25631'
    };
    var callWebchat=function(){var w=window;var ic=w.Clustaar;if(typeof ic==='function'){ic('reattach_activator');ic('update',clustaarSettings)}else{var d=document;var i=function(){i.c(arguments)};i.q=[];i.c=function(args){i.q.push(args)};w.Clustaar=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=!0;s.src='https://webchat.clustaar.io/assets/scripts/webchat.js';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x)};l();if(w.attachEvent){w.attachEvent('onload',l)}else{w.addEventListener('load',l,!1)}}};callWebchat();
</script>