Skip to main content

​
Complete Guide to Users

botBrains keeps track of your users by default. You can annotate additional user data via the Web SDK. New data will always overwrite old data.
We store phone numbers in E.164 (+4915168433056), but allow common variations such as +49 30 12345678 or +1 (415) 555-2671 for the input

​
Annotate Users

$botbrains.push(["set", "user.data", {
	first_name: "Liam",
	last_name: "van der Viven",
	email: "liam@botbrains.io",
	phone: "+4915168433056"
}]);

​
Arbitrary Data

You can also annotate custom values with the external_attributes JSON. By default we merge external attributes, keeping unset values, to deactivate merging the top level keywords set merge_external_attributes to false
The total JSON size of external_attributes must be below 8KB.
$botbrains.push(["set", "user.data", {
	first_name: "Liam",
	last_name: "van der Viven",
	email: "liam@botbrains.io",
	phone: "+4915168433056",
	external_attributes: {
		"plan": "basic",
		"joined_on": "2024-01-01"
	},
	merge_external_attributes: true // default
}]);

​
Session Continuity

A session allows users to retrieve their past conversations. By default, botBrains enables session continuity within the same browser and all subdomains. This means a user that goes to your landing page on www.acme.com and then signs into app.acme.com will still be identified as the same user. You can opt-in to cross device session continuity by manually the user via the user.identify action in the SDK.

​
User Identificiation

User Identification must be implemented correctly on your part. Make sure to read the Security section to learn how.
$botbrains.push(["do", "user.identify", ["user_01234567890", {
	first_name: "Liam",
	last_name: "van der Viven",
	email: "liam@botbrains.io",
	phone: "+4915168433056",
	external_attributes: {
		"plan": "basic",
		"joined_on": "2024-01-01"
	}
}]]);
The user_01234567890 key here is what we call the external_id of a user. Two users with the same external_id will be able to reach each others conversations.

​
🚨 Security 🚨 - READ THIS

Not following these recommendations make the conversations of your users vulnerable to impersonation. botBrains does not take responsibility for misconfigured systems.
Since we allow you to explicitly set if users are the same or different and thus retrieve sensitive information such as past conversations, we need to be careful in choosing the external_id. You have two options:
  1. User-Specific Secret Randomly generate an id, store with your user and sent to your frontend. Do not use or leak this anywhere.
  2. Verified User ID (✅ Recommended) Possibly known ID that is added with a signature of a shared secret of your backend and the botBrains Platform.

​
User-Specific Secret

You associate your user with an unique identifier (e. g. UUID) that should never be known by other users. User Ids are commonly leaked in your app supports Teams, Collaborates, Share Links and other features, thus your user_id is usually a bad choice. Insecure External Ids are:
  • timestamps
  • email
  • phone
  • serial identifiers (e. g. user id 38992)
  • any text shorter than 16 character is disallowed
Good External Ids are:
  • UUIDs
  • anything with large entropy

​
Verified User Id

✅ Recommended
Alternatively, we suggest you use user verification. User Verficiation works by signing the values you pass to the SDK on a backend server and passing it through your frontend into the Web SDK. The signature is the HMAC, that is the hash of your user identifier and a shared secret known to your backend servers and the botBrains platform.
  • We will share the verification secret with you on request, this is currently not expose through our platform
The Verification Secret must never be sent to the frontend. The hash must be computed on the backend and send to the frontend, which invokes the Web SDK.
Below you will find example code of the business logic your backend server needs to perform. 
import hmac
import hashlib

def generate_hmac(secret_key: str, user_id: str) -> str:
    key = secret_key.encode()
    message = user_id.encode()

    hmac_digest = hmac.new(key, message, hashlib.sha256).hexdigest()
    return hmac_digest

secret_key = "your_secret_key"
user_id = "user_123456789"
external_id_signature = generate_hmac(secret_key, user_id)
print(secret_key, "+", user_id, "HMAC:", external_id_signature)

const crypto = require("crypto");

function generateHmac(secretKey, userId) {
    return crypto.createHmac("sha256", secretKey).update(userId).digest("hex");
}

const secretKey = "your_secret_key";
const userId = "user_123456789";
const externalIdSignature = generateHmac(secretKey, userId);
console.log(secretKey, "+", userId, "HMAC:", externalIdSignature);

function generate_hmac($secret_key, $user_id) {
    return hash_hmac('sha256', $user_id, $secret_key);
}

$secret_key = "your_secret_key";
$user_id = "user_123456789";
$external_id_signature = generate_hmac($secret_key, $user_id);
echo "$secret_key + $user_id HMAC: $external_id_signature\n";
On the client, you then call user.identify with external_id_signature. Note that we expect the hex-encoded version of the resulting 32 bytes of hmac, totaling 64 characters. 
$botbrains.push(["do", "user.identify", ["user_123456789", {
	first_name: "Liam",
	last_name: "van der Viven",
	email: "liam@botbrains.io",
	phone: "+4915168433056",
	external_attributes: {
		"plan": "basic",
		"joined_on": "2024-01-01"
	},
	// NEW!
	external_id_signature: "88dddece03a2ac2b6d724287cb2d6ca6de79c0e3428e6b75c510676262157649"
}]]);
Contact support support@botbrains.io if you need help computing the HMAC in other programming languages.

​
Verifying email and phone

You can also verify the email and phone of a user, using the same HMAC procedure shown above, just using the email and phone values instead of the user_id. 
import hmac
import hashlib

def generate_hmac(secret_key: str, user_id: str) -> str:
    key = secret_key.encode()
    message = user_id.encode()

    hmac_digest = hmac.new(key, message, hashlib.sha256).hexdigest()
    return hmac_digest

secret_key = "your_secret_key"
phone = "+4915168433056"
email = "liam@botbrains.io"
phone_signature = generate_hmac(secret_key, phone)
email_signature = generate_hmac(secret_key, email)
print(phone_signature, email_signature)

$botbrains.push(["do", "user.identify", ["user_123456789", {
	email: "liam@botbrains.io",
	phone: "+4915168433056",
	// ...
	phone_signature: "be9b0317ab56c0a76cc6dd16881f257704c5276ce440ac3307cf579dc5d7826b",
	email_signature: "d3763347cb7669fc04ff76cac2907cd5e3e0c12a560a1bf67b4baab8af2dad74"
}]]);

​
Finish

We’re happy to help you setup verified users, contact support@botbrains.io to schedule a quick meeting.