Send logged-in user data from your database or third-party tool

Updated September 26, 2022

Imagine this scenario. A user logs into your app. Creates a conversation with your support team from the Messenger but chooses not to enter their email address. For whatever reason, closes the browser and doesn't return until later. There is no way of knowing who the person is and when they come back, they lose all their conversation history leading to a really terrible user experience.

To avoid this, you can track your logged-in users as soon as they log in to your app without them having to submit their email address again in the Messenger or any of the Gist forms, by simply letting Gist know their email address, which you would know when they logged-in to your app.

The primary way of sending your logged-in user data in Gist is the 'identify' method. The identify method allows you to let Gist know who the visitor is and tie them to a unique identifier so their activity and conversation history is maintained across multiple visits to your website.

In order to set this up correctly, your web developer must be involved to make sure you are sending the data correctly.

So, what is the Identify call?

The Gist identify method not just allows you to let Gist know who the user is but it also allows you to send additional information about your users to Gist using JavaScript, saving them as Contact Properties. This allows you to use this information to segment the contacts and send targeted communication.

The Identify call

gist.identify("12345", {
    "email": "johndoe@tacos.com",
    "name": "John Doe",
    "subdomain": "app", // Put quotes around text strings
    "active_accounts": 1872, // Send numbers without quotes
    "last_paid_at" : 1283495946, // Send dates in unix timestamp format and end key names with "_at"
    "teammates": null, // Send null when no value exists for a user
    "tags": "Free, popular", // Multiple tags can be added separated by comma
    "overwrite_tags": false // Defaults to true. If set to false, will merge the tags
});

The first part, 12345, should be a case-sensitive string containing the User ID for a user on your site, typically from your own user database, or empty string ("") if it is not known. Must be fewer than 255 characters.

The second part is a series of key-value pairs inside a JSON object. The key provides the Contact Property name and the value defines both the type of the contact property and its value for the contact.

Also, here are some important notes:

  • Both user_id and email are required in the gist.identify() call.
  • Property names must not contain Periods ('.') or Dollar ('$')
  • Property values must be JSON Strings, Numbers or Booleans. Objects and Arrays will be rejected.
  • Properties keys cannot contain special characters such as ~`!@#%^&*'{}|\'" or even the NULL character.
  • Property keys are case-sensitive.
  • Property values of string type are allowed to have up to 255 characters.

Make sure to double check that your Property keys always have a JSON-valid value - double quotes around strings and send null as a value when there isn't a value for that user.

When should you call identify?

Gist recommends that you make the identify call:

  • When a user registers
  • When a user logs in
  • When a user updates their info (when they add a new address, billing method, change plans, etc.)
  • Upon loading any pages that are accessible by a logged-in user (optional)

An example Identify call

Many products include some sort of tiered pricing plans. Using gist.identify to attach this information to your users' Gist profiles can help you target those users and send relevant messages.

Gist's own pricing tiers include Free, Support, Marketing, and All in One plans. We use the identify  call ourselves so we can send pre-sale messages to Free users and customer success messages to Paid users etc.

When someone visits Gist, we pull their account plan from our database and include that into an identify call like this:

gist.identify("12345", {
    "email": "johndoe@example.com",
    "plan": "Pro"
});

Once you have your properties added to Gist, you can head over to the ‘Contacts’ page and apply filters based on contact properties to group your contacts.

Need Help?

If you have any questions, please start a Live Chat. Just "Click" on the Chat Icon in the lower right corner to talk with our support team.

Was this article helpful?