Custom Visitor Identities

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

ServiceBell("identify",
  YOUR_UNIQUE_CUSTOM_ID, // String or integer, replace with your own custom unique value
  {
    email: "[email protected]", // REQUIRED: Required to create or associate a contact with the visitor.
    displayName: "Jessie", // Changes the name of the visitor in the dashboard
    avatar: "https://example.com/avatar.png", // Changes the avatar of the visitor in the dashboard
    tag: "PAID_PLAN", // or "NEW_PLAN" or "TRIAL_PLAN": Adds an icon next to the visitor name in the dashboard
    anyDataYouWant: "hotdogs", // Any other custom data can be added as well
  },
);

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:

• The email key is required. Email addresses are used to create or associate a contact with the visitor. If the email key is not present the metadata will be ignored.

• 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.

Custom Metadata Length Restriction

Custom Metadata is limited on a per-visitor basis. Each visitor is limited to 1024 bytes for metadata storage. When adding custom metadata, if the change would cause the stored custom metadata to exceed this limit, the change will not persist and the custom metadata will be left in the state prior to the update being attempted.

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+)

import hmac
import hashlib
import json

def generate_servicebell_identity_hash(user_id: str, email: str) -> str:
  data = {"id": user_id}
  if email:
      data["email"] = email
  return hmac.new(
      bytes(
          os.environ.get("SERVICEBELL_IDENTITY_SECRET_KEY"),
          encoding="utf-8",
      ),
      bytes(
          json.dumps(data, separators=(",", ":")),
          encoding="utf-8",
      ),
      digestmod=hashlib.sha256,
  ).hexdigest()

Node.js

import crypto from 'crypto';

function generateServiceBellIdentityHash(id, email) {
  const data = { id: id };
  if (email) {
    data.email = email;
  }
  return crypto
    .createHmac('sha256', process.env.SERVICEBELL_IDENTITY_SECRET_KEY)
    .update(JSON.stringify(data))
    .digest('hex');
}

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.

// This assumes you have an API endpoint at /api/servicebell-identity-hash
// that returns the hash as text, and assumes that you have some kind of
// user object in Javascript that has an id and email. Your implementation may
// look different.

fetch("/api/servicebell-identity-hash").then(async res => {
  const authHash = await res.text();
  ServiceBell("identify",
    user.id,
    { email: user.email },
    authHash,
  );
});

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.