Classic Data API
This page documents the Classic Data API, a set of JavaScript classes used to synchronize user and conversation data. New TalkJS integrations should manage data using the simpler and more powerful JavaScript Data API instead.
UserRef is part of the simpler and more powerful Data API.
A user of your app. TalkJS uses the id to uniquely identify this user. All other fields of a User are allowed to vary over time and the TalkJS database will update its fields accordingly.
| Constructor | Create a TalkJS User |
The unique ID which is used to identify the user in TalkJS
The User's name which will be displayed on the TalkJS UI
Availability acts similarly to welcomeMessage but appears as a system message.
Allows you to set custom metadata for the User
One or more email address belonging to the User. The email addresses will be used for Email Notifications if they are enabled.
The locale field expects an IETF language tag. See the localization documentation.
One or more phone numbers belonging to the User. The phone number will be used for SMS Notifications (this feature requires standard plan and up).
An optional URL to a photo which will be displayed as the user's avatar
TalkJS supports multiple sets of settings, called "roles". These allow you to change the behavior of TalkJS for different users. You have full control over which user gets which configuration.
The default message a user sees when starting a chat with that person
new User(options)
Create a TalkJS User
Use this constructor to create or update user data. The user is synchronized with the TalkJS backend if they are the current user in a session. If they are not the current user, and they are part of an existing conversation, they will be synchronized when the UI is mounted.
The fields id, name and email are required. A warning will be emitted if role is not specified.
Set email to null if you want to use TalkJS without email fallback.
Parameters
interface UserOptions
The unqiue ID which is used to identify the user in TalkJS
The User's name which will be displayed on the TalkJS UI
Allows you to set custom metadata for the User
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
One or more email address belonging to the User. The email addresses will be used for Email Notifications if they are enabled.
Set to null to delete the existing value(s) (if any). When omitted or undefined, the existing value(s) remain unchanged.
The locale field expects an IETF language tag. See the localization documentation.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
One or more phone numbers belonging to the User. The phone number will be used for SMS Notifications (this feature requires standard plan and up).
Set to null to delete the existing value(s) (if any). When omitted or undefined, the existing value(s) remain unchanged.
An optional URL to a photo which will be displayed as the user's avatar
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
TalkJS supports multiple sets of settings, called "roles". These allow you to change the behavior of TalkJS for different users. You have full control over which user gets which configuration.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
The default message a user sees when starting a chat with that person
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Availability acts similarly to User.welcomeMessage but appears as a system message.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
ConversationRef is part of the simpler and more powerful Data API.
A Conversation Builder represents a conversation that is about to be created, fetched, or updated. You can use this object to set up or modify a conversation before showing it.
To create a ConversationBuilder, call Session.getOrCreateConversation.
Note: any changes you make here will not be sent to TalkJS immediately. Instead, instantiate a TalkJS UI using methods such as Session.createInbox.
| leave Classic | Removes the current user from this conversation. |
| sendMessage Classic | Sends a text message in a given conversation. |
| setAttributes Classic | Used to set certain attributes for a specific conversation |
| setParticipant Classic | Sets a participant of the conversation. |
Allows custom conversation metadata to be stored in the form { [name: string]: string }
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
An optional URL to a photo which will be shown as the photo for the conversation.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
An optional conversation subject which will be displayed in the chat header.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Messages which are sent at the beginning of a chat. In this case the messages will appear as system messages.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
conversationBuilder.leave(): Promise<boolean>
The Data API equivalent of leave is ParticipantRef.delete:
1session.conversation(convId).participant(session.currentUser).delete();
Removes the current user from this conversation.
Returns
A promise that resolves with true upon success (indicating that the user has been removed from this conversation), or false when the user did not have the appropriate permissions, as defined on the "Chat UI" page in the TalkJS dashboard). The promise may reject in case of an unexpected error.
conversationBuilder.sendMessage(text, options): Promise<void>
The Data API equivalent of sendMessage is ConversationRef.send:
1session.conversation(convId).send("Hello");
It can also send formatted messages, file attachments, and map locations.
Sends a text message in a given conversation.
Parameters
The message body that is to be sent.
interface SendMessageOptions
An object with any custom data that you may wish to associate with this message. The custom data is sent back to you via webhooks and the REST API.
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Returns
conversationBuilder.setAttributes(attributes)
The Data API equivalent of setAttributes is ConversationRef.set:
1session.conversation(convId).set({ subject: "Booking question" });
Used to set certain attributes for a specific conversation
Parameters
interface ConversationAttributes
Conversation attributes that can be set using ConversationBuilder.setAttributes
Custom metadata that is stored with the conversation
Set any property to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
The URL of a photo to be used for this conversation in the TalkJS UI in case there are more than 2 participants (TalkJS shows the photo of the other participant in a 1-on-1 conversation)
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
A human-readable subject of the conversation. Supports formatted links in a Markdown-style syntax, e.g. Beautiful <https://example.com/booking/18644|home by the sea>!. URLs and email addresses are made clickable, and emojis made to work cross-platform.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Messages which are sent at the beginning of a chat. In this case the messages will appear as system messages.
Set to null to delete the existing value (if any). When omitted or undefined, the existing value remains unchanged.
Returns
Usage
1conversation.setAttributes({subject: "Booking question"});
Setting the
custom.sold and custom.itemId properties
1conversation.setAttributes({custom:2 {3 sold: "true",4 itemId: "720"5 }6});
If the conversation has any pre-existing custom properties, they will not be removed unless you set them to null.
conversationBuilder.setParticipant(user, settings)
The Data API equivalent of setParticipant is ParticipantRef.set:
1session.conversation(convId).participant(userId).set({ notify: false });
Sets a participant of the conversation.
This method is idempotent and can be called multiple times.
Parameters
A User object that identifies the person who is a participant of the conversation. The user is uniquely identified by their id; all other fields (name, photo etc) are overwritten in the TalkJS database each time they change.
An optional setting of participation, can be an initial access right or if user should be notified.
interface ParticipationSettings
Specifies access and notification settings for a given user's participation to a given conversation. Used in ConversationBuilder.setParticipant.
Specifies the participant's access permission for a conversation. See ConversationBuilder.setParticipant
When omitted or undefined, the existing value remains unchanged.
Specifies the participants's notification settings. See ConversationBuilder.setParticipant
When omitted or undefined, the existing value remains unchanged.