Users / Participants
A TalkJS user is a person (or a group of persons) 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 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 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.
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
"user_5" or something like that.
|id||string or number||As described above. |
|name||string||The user's name or username - use whatever you want others to see when communicating with this user. |
|string||Zero or more email addresses used for offline email notifications. |
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. |
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. |
|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. |
Read more about language support.
|welcomeMessage||string||An optional welcome text shown to another user at the start of a conversation. |
|availabilityText Deprecated||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.
|role||string||One of the user roles that you set up in the TalkJS Dashboard for this user. You can vary many settings per user role, such as the content of their email/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.
|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: |
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.
name are required for TalkJS to function. All other fields are optional. Note that without
role set to valid values, TalkJS can't send email notifications to users who are offline.
phone. The REST API accepts only arrays of strings.
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
- We don't contact your users (except of course to send them chat notifications).
Also, if you want to ban a user from all chats, we have a tutorial that shows you how to accomplish that. The tutorial also showcases how to ensure the integrity of your user's data by using Identity Verification and disabling client-side conversation syncing.