Custom Visitor Identities

Search…
You can provide custom visitor identity information to the Service Bell dashboard, which will allow you to deduplicate visitors and give customer support agents information about who they're helping.
Code Sample
1
ServiceBell("identify",
2
 YOUR_UNIQUE_CUSTOM_ID, // String or integer, replace with your own custom unique value
3
 {
4
 displayName: "Jessie", // Changes the name of the visitor in the dashboard
5
 email: "[email protected]", // Changes the email of the visitor in the dashboard
6
 avatar: "https://example.com/avatar.png", // Changes the avatar of the visitor in the dashboard
7
 tag: "PAID_PLAN", // or "NEW_PLAN" or "TRIAL_PLAN": Adds an icon next to the visitor name in the dashboard
8
 anyDataYouWant: "hotdogs", // Any other custom data can be added as well
9
 },
10
);
Copied!
Providing a Unique Custom ID
In order to fully use the identify api, you must have a unique custom identifier available in Javascript to attach to the visitor, and use that to replace YOUR_UNIQUE_CUSTOM_ID above.
This value is typically a user ID or an email address. Using a static value or a value that can collide with multiple visitors (such as an IP address or a name) can cause loss of data and disconnected sessions.
If you do not have a custom identifier but would still like to set custom properties to view in the dashboard, you can pass undefined as the unique identifier. Subsequent visits from this visitor may not have the associated metadata, and their session history will be incomplete.
Custom Metadata
The custom data object can provide customer service agents any other details that may be important to the session. The object has a few implementation notes and limits:
Keys must be JSON-serializable values.
Repeated calls to identify will overwrite previous data, and should be called on every session.
New keys passed into the custom data object will be added on to previous custom data, so you don't have to pass the whole object every time, and can pass keys that you may not have until later into the visitor's session.
If you want to remove a key, you must pass null for its value. Simply omitting it will keep the previous value.
Secure Identities
For security-conscious customers, we recommend validating user identities on your server before identifying them to ServiceBell. This is done by generating a unique hash of the visitor's identity before sending it to ServiceBell, using a secret key on your server.
You only need to hash the custom user ID, and optionally the email if you're providing one in the custom metadata. Below are examples of how to generate this hash on your server.
Python (3+)
Node.js
1
import hmac
2
import hashlib
3
import json
4
​
5
def generate_servicebell_identity_hash(user_id: str, email: str) -> str:
6
 data = {"id": user_id}
7
 if email:
8
 data["email"] = email
9
 return hmac.new(
10
 bytes(
11
 os.environ.get("SERVICEBELL_IDENTITY_SECRET_KEY"),
12
 encoding="utf-8",
13
 ),
14
 bytes(
15
 json.dumps(data, separators=(",", ":")),
16
 encoding="utf-8",
17
 ),
18
 digestmod=hashlib.sha256,
19
 ).hexdigest()
Copied!
1
import crypto from 'crypto';
2
​
3
function generateServiceBellIdentityHash(id, email) {
4
 const data = { id: id };
5
 if (email) {
6
 data.email = email;
7
 }
8
 return crypto
9
 .createHmac('sha256', process.env.SERVICEBELL_IDENTITY_SECRET_KEY)
10
 .update(JSON.stringify(data))
11
 .digest('hex');
12
}
Copied!
If you don't see your server's language listed above, you can use any technique to generate an equivalent HMAC SHA256 hash of the data in JSON string form. For example, an ID of "123" and an email of "[email protected]" would be a hash of:
{"id":"123","email":"[email protected]"}
Make sure the JSON string is in the correct order (id first, email second) and that it has no unnecessary whitespace. Any difference in the JSON string will result in mismatching hashes.
You'll take the hash generated from your server and add it as the third argument to the ServiceBell("identify") call, like so.
1
// This assumes you have an API endpoint at /api/servicebell-identity-hash
2
// that returns the hash as text, and assumes that you have some kind of
3
// user object in Javascript that has an id and email. Your implementation may
4
// look different.
5
​
6
fetch("/api/servicebell-identity-hash").then(async res => {
7
 const authHash = await res.text();
8
 ServiceBell("identify",
9
 user.id,
10
 { email: user.email },
11
 authHash,
12
 );
13
});
Copied!
You can retrieve your secure identity secret key from the Security Settings page on the ServiceBell dashboard. Once you've implemented everything above, you can toggle on requiring secure identities. This will cause any identity sent without a valid hash to be rejected.
Controlling the Widget
Listening to Events
Last modified 2d ago
Copy link
Contents
Code Sample
Custom Metadata
Secure Identities