Users

A TalkJS user is a person or a group of people 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.

Map 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 IDs 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

FieldTypeDescriptionExample
id
string | numberAs described above.12345, "2092ca38-6955-4d05-bc03-9c686648d9f4"
name
stringThe user's name or username - use whatever you want others to see when communicating with this user."Linda"
email
string[]Zero or more email addresses used for offline email notifications.
Read more about email notifications.		["[email protected]"], []
phone
string[]Zero or more phone numbers used for offline SMS notifications. Use the E.164 international phone number format without spaces.
Read more about SMS notifications.		["+14155552671", "+31612345678"], []
photoUrl
stringThe URL of a photo or avatar of this user. Shown to others in conversations with this user."https://talkjs.com/images/avatar-1.jpg"
locale
stringAn IETF language tag that sets a language and date format for this user. Note: you set the default locale for your entire app on the Settings page of your TalkJS dashboard.
Read more about localization.		"fr-FR", "cs-CZ"
welcomeMessage
stringAn optional welcome text shown to another user at the start of a conversation."Hey there, any questions? Let me know how I can help"
availabilityText Deprecated
stringDeprecated: This feature has been deprecated in favor of conversation.welcomeMessages.
An optional neutral text, rendered as a System Message at the start of this conversation.		"We're usually online during office hours"
role
stringA user role that you can set up from the Roles page of your TalkJS dashboard. You can vary many settings per user role, such as the content of their email or SMS notification, the look and feel of the UIs, and forbidden words.
Make sure the role corresponds precisely to a role name you chose in the dashboard.		"buyer", "employee".
custom
object of stringsJSON-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 or 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.
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 for example JSON.stringify or similar functions). See also: Conversation.custom.		{"country":"nl", "auhToken": "z5i6jir5w6pczg0r"}

Only id and name are required for TalkJS to function. All other fields are optional. Note that without email and role 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.

Privacy and data security

TalkJS takes privacy seriously, and only uses your user data where TalkJS features require it. Because of this:

  • TalkJS doesn't track your user's behavior
  • Sensitive data is [suppressed] when obtained from the Javascript SDK. To access these fields, you can use the REST API.
  • We don't contact your users, except to send them chat notifications.

If you want to ban a user, follow this tutorial on how to ban a user from all chats. The tutorial also showcases how to ensure the integrity of your user's data by using Identity Verification and disabling client-side conversation syncing.

Further reading