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.

class User

New TalkJS integrations should use UserRef via Session.user() 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.

Method Overview

Constructor

Create a TalkJS User

Properties

id
: string

The unique ID which is used to identify the user in TalkJS

name
: string

The User's name which will be displayed on the TalkJS UI

availabilityText (optional)
: string | null

Availability acts similarly to welcomeMessage but appears as a system message.

custom (optional)
: { [name: string]: string | null } | null

Allows you to set custom metadata for the User

email (optional)
: string | Array<string> | null

One or more email address belonging to the User. The email addresses will be used for Email Notifications if they are enabled.

locale (optional)
: string | null

The locale field expects an IETF language tag. See the localization documentation.

phone (optional)
: string | Array<string> | null

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).

photoUrl (optional)
: string | null

An optional URL to a photo which will be displayed as the user's avatar

role (optional)
: string | null

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.

welcomeMessage (optional)
: string | null

The default message a user sees when starting a chat with that person

Deprecated configuration (optional)
: string | null
Deprecated. Please use role instead.

Constructor (1)

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

options
: UserOptions
interface UserOptions
id
: string | number

The unqiue ID which is used to identify the user in TalkJS

name
: string

The User's name which will be displayed on the TalkJS UI

custom (optional)
: { [name: string]: string | null } | null

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.

email (optional)
: string | Array<string> | null

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.

locale (optional)
: string | null

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.

phone (optional)
: string | Array<string> | null

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.

photoUrl (optional)
: string | null

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.

role (optional)
: string | null

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.

welcomeMessage (optional)
: string | null

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.

Deprecated availabilityText (optional)
: string | null

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.

Deprecated. Please use Conversation​.welcomeMessages instead.
Deprecated configuration (optional)
: string | null
Deprecated. Please use role instead.

Constructor (2)

new User(id)

Create a TalkJS User

Only use this constructor if you're sure that a user by the given id already exists in TalkJS (for instance, because you synchronized it via the REST API). Otherwise use the new User(options: object): constructor instead.

Parameters

id
: string | number

interface ConversationBuilder

New TalkJS integrations should use ConversationRef via Session.conversation() instead. 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.

Method Overview

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.

Properties

custom (optional)
: { [name: string]: string | null } | null

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.

photoUrl (optional)
: string | null

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.

subject (optional)
: string | null

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.

welcomeMessages (optional)
: Array<string> | null

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.

Classic leave

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

Promise<boolean>

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.

Classic sendMessage

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

text
: string

The message body that is to be sent.

options (optional)
: SendMessageOptions
interface SendMessageOptions
custom (optional)
: CustomData

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

Promise<void>

Classic setAttributes

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

attributes
: ConversationAttributes
interface ConversationAttributes

Conversation attributes that can be set using ConversationBuilder​.setAttributes

custom (optional)
: { [key: string]: string | null } | null

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.

photoUrl (optional)
: string | null

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.

subject (optional)
: string | null

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.

welcomeMessages (optional)
: Array<string> | null

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

void

Usage

Example 1
Setting the conversation subject 
1conversation.setAttributes({subject: "Booking question"});
Example 2
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.

Classic setParticipant

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

user
: User

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.

settings (optional)
: Partial<ParticipationSettings>

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.

access (optional)
: "Read" | "ReadWrite"

Specifies the participant's access permission for a conversation. See ConversationBuilder​.setParticipant

When omitted or undefined, the existing value remains unchanged.

notify (optional)
: boolean | "MentionsOnly"

Specifies the participants's notification settings. See ConversationBuilder​.setParticipant

When omitted or undefined, the existing value remains unchanged.

Returns

void