Users
A TalkJS user is a person or a group of people who uses your app.
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.
When you send user data to TalkJS, you need to provide a user ID for each user. Each user ID must be:
- Unique: No two distinct users can have the same user ID.
- Permanent: Once assigned, a user must always keep the same user ID. If you change a user's user ID, the user might lose access to their chat.
A best practice is just to use the user ID that's already used inside your own database.
Any time someone loads TalkJS and identifies with a specific user ID, TalkJS can load that user's old messages — even on different devices. Authentication (Identity verification) makes this secure.
Sometimes it can be effective to make a group of users act as a single TalkJS user. For example, a team of colleagues may want 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, for example turn it into "team_5" and "user_5" or something like that.
| Field | Type | Description | Example |
|---|---|---|---|
string | number | As described above. | 12345, "2092ca38-6955-4d05-bc03-9c686648d9f4" | |
string | The user's name or username - use whatever you want others to see when communicating with this user. | "Linda" | |
string[] | Zero or more email addresses used for offline email notifications. Read more about email notifications. | ["[email protected]"], [] | |
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"], [] | |
string | The URL of a photo or avatar of this user. Shown to others in conversations with this user. | "https://talkjs.com/images/avatar-1.jpg" | |
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 on the Settings page of your TalkJS dashboard. Read more about localization. | "fr-FR", "cs-CZ" | |
string | An optional welcome text shown to another user at the start of a conversation. | "Hey there, any questions? Let me know how I can help" | |
string | Deprecated: 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" | |
string | A 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". | |
| 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 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.
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 authentication (identity verification) and disabling client-side conversation syncing.
- The Talk.User class in the JavaScript SDK reference
/usersin the REST API