A TalkJS user is a person (or a group of persons) who uses your app.

It's your user

It's usually best to map a user in your own database one-to-one to a TalkJS user. In fact, the only reason TalkJS tracks user information at all is so we can display a user's name, send them email notifications, and so on.

TalkJS is designed from the ground up around the idea that this data is your user data, and we only hold it for being able to deliver a good chat service. This means that:

  • TalkJS only collects the user data that is needed to make TalkJS work, and nothing else.
  • The JavaScript SDK is designed such that user data is synchronized all the time while they're logged into your app.

The last point means that in practice, TalkJS holds an up-to-date copy of your user. How this works is that each time a TalkJS Session is started, your code initializes the session with the user's data. On a classical server-side rendered page, this happens every time the user navigates. This way, even when your user changes their information, it'll be reflected at TalkJS right after.

You can also use the REST API to programmatically synchronize user data at the appropriate time, if you prefer.

The user ID

When sending user data to TalkJS, you need to provide us with a user ID. Any time someone loads TalkJS and identifies with that user ID, TalkJS will be able to load that user's old messages - even on different devices. (note, we use Identity Verification to make this secure)

It's best if you just use the user's user ID that is used inside your own database as well.

Mapping multiple users to a single TalkJS user

Sometimes, it can be effective to make a group of users "be" a single TalkJS user. For example, this is practical if a team of colleagues wants to chat on your platform with another person, but it should appear as if it's a single person talking.

In this case, send a user ID to TalkJS that is not the same as your users' real ID. For instance, it might be appropriate to use the team ID for a TalkJS user ID.

Make sure that user ID's don't collide! If you use increasing numbers for both your user IDs and your team IDs, then TalkJS will think that user 5 and team 5 is the same user. If this might happen, it may be better to prefix your TalkJS user IDs, eg turn it into "team_5" and "user_5" or something like that.

User data

Field Type Description
id string or number

As described above.

Examples: 12345, "2092ca38-6955-4d05-bc03-9c686648d9f4"

name string

The user's name or username - use whatever you want others to see when communicating with this user.

Example: "Linda"

email string[]

Zero or more email addresses used for offline email notifications.

Examples: ["[email protected]"], []
Read more about email notifications.

phone string[]

Zero or more phone numbers used for offline SMS notifications. Use the E.164 international phone number format without spaces.

Examples: ["+14155552671", "+31612345678"], []
Read more about SMS notifications.

photoUrl string

The URL of a photo or avatar of this user. Shown to others in conversations with this user.

Example: "https://demo.talkjs.com/img/alice.jpg"

locale string

An IETF language tag that sets a language and date format for this user. Note: you set the default locale for your entire app in the TalkJS Dashboard.

Examples: "fr-FR", "cs-CZ"
Read more about language support.

welcomeMessage string

An optional welcome text shown to another user at the start of a conversation.

Example: "Hey there, any questions? Let me know how I can help"

availabilityText string

An optional neutral text, rendered as a System Message at the start of this conversation.

Example: "We're usually online during office hours"

configuration string

One of the user configurations that you set up in the TalkJS Dashboard for this user. You can vary many settings per user configuration, such as the content of their email/sms notification, the look and feel of the UIs and forbidden words.

Example: "buyer", "employee".

Make sure the configuration corresponds precisely to a configuration name you chose in the Dashboard.

custom object of strings

JSON-structured custom data that you wish to associate to this user. TalkJS does nothing with this data except make it available in the events that we send to your code and in your Email/SMS notification templates. You can use custom data for all kinds of purposes, such as customizing a user's email notification text, transmitting contextual user data, or making email login tokens.

Example: {"country":"nl", "auhToken": "z5i6jir5w6pczg0r"}

Must be an object with string keys and string values; arbitrarily deeply nested JSON is not supported. If you need structured data for one of your custom fields, consider serializing it yourself (using e.g. JSON.stringify or similar functions) See also Conversation.custom.

Only id and name are required for TalkJS to function. All other fields are optional. Note that without email and configuration set to valid values, TalkJS can't send email notifications to users who are offline.

Note: the JavaScript SDK also accepts single strings for email and phone. The REST API accepts only arrays of strings.

It's your user

We take privacy seriously, and we wouldn't need your user data at all if the TalkJS features wouldn't require it. Because of this:

  • We don't track your user's behavior
  • Sensitive data is [surpressed] when obtained from the Javascript SDK, to access these fields you can call make a call to our API.
  • We don't contact your user (except of course to send them a notifications on behalf of a different user they're engaging with).

Further reading