TalkSession

This is the entry point to the standalone JavaScript Data API. Use TalkSession if you have installed the JavaScript Data API as a separate npm package, @talkjs/core.

If you use the JavaScript Data API as part of the JavaScript SDK, use Session instead, which includes all the methods and properties of TalkSession documented below.

Create a session

The getTalkSession function returns a TalkSession object for a given app ID and user ID:


1import { getTalkSession } from '@talkjs/core';
2
3const session = getTalkSession({
4  appId: '<APP_ID>',
5  userId: '<USER_ID>',
6});

The following options are available when calling getTalkSession:

Name	Type	Description
appId Required	`string`	Your app's unique TalkJS ID. Get it from the Settings page of the dashboard.
userId Required	`string`	The `id` of the user you want to connect and act as. Any messages you send will be sent as this user.
token	`string`	A token to authenticate the session with. Pass `token` if you use standard (non-refreshable) authentication.
tokenFetcher	`() => Promise<string>`	A callback that fetches a new token from your backend and returns it. Pass `tokenFetcher` if you use authentication with refreshable tokens. If this callback throws an error or returns a rejected promise, the session will terminate. Your callback should retry failed requests.

Calling getTalkSession twice for the same app and user will return the same object both times, rather than creating a new session. This means that the token and tokenFetcher properties are ignored if there is already an active session for that user.

Properties

Field	Type	Description
currentUser	`UserRef`	A reference to the user whose ID you passed to `getTalkSession`.

Methods

The TalkSession object has the following methods.

user


1user(id: string): UserRef;

Returns a reference to the user with the specified ID.

conversation


1conversation(id: string): ConversationRef;

Returns a reference to the conversation with the specified ID.

onError


1onError(handler: (error: Error) => void): Subscription;

Attaches a listener which gets called when the TalkSession encounters an unrecoverable error. For example, if the session cannot authenticate, or if you specify an incorrect app ID.

If the session has already terminated, the handler will be called immediately.

Returns

A subscription object. Call Subscription.unsubscribe() to detach the listener.

uploadFile


1uploadFile(data: Blob, metadata: GenericFileMetadata): Promise<FileToken>;

Uploads a generic file without any additional metadata.

This function does not send any message, it only uploads the file and returns a file token. To send the file in a message, pass the file token in a SendFileBlock when you call ConversationRef.send.

See the documentation for more information about sending files in messages.

If the file is a video, image, audio file, or voice recording, use one of the other functions like uploadImage instead.

Parameters

Name	Type	Description
data	`Blob`	The binary file data. Usually a File.
metadata	`GenericFileMetadata`	Information about the file, see below.

GenericFileMetadata

Property	Type	Description
filename Required	`string`	The name of the file, including the extension.

Returns

A promise that resolves to a FileToken that can be used to send the file in a message.

uploadImage


1uploadImage(data: Blob, metadata: ImageFileMetadata): Promise<FileToken>;

Uploads an image with image-specific metadata. This is a variant of uploadFile used for images.

Parameters

Name	Type	Description
data	`Blob`	The binary file data. Usually a File.
metadata	`ImageFileMetadata`	Information about the image, see below.

ImageFileMetadata

Property	Type	Description
filename Required	`string`	The name of the file, including the extension.
width	`number`	The width of the image in pixels, if known.
height	`number`	The height of the image in pixels, if known.

Returns

A promise that resolves to a FileToken that can be used to send the file in a message.

uploadVideo


1uploadVideo(data: Blob, metadata: VideoFileMetadata): Promise<FileToken>;

Uploads a video with video-specific metadata. This is a variant of uploadFile used for videos.

Parameters

Name	Type	Description
data	`Blob`	The binary file data. Usually a File.
metadata	`VideoFileMetadata`	Information about the video, see below.

VideoFileMetadata

Property	Type	Description
filename Required	`string`	The name of the file, including the extension.
width	`number`	The width of the video in pixels, if known.
height	`number`	The height of the video in pixels, if known.
duration	`number`	The duration of the video in seconds, if known.

Returns

A promise that resolves to a FileToken that can be used to send the file in a message.

uploadAudio


1uploadAudio(data: Blob, metadata: AudioFileMetadata): Promise<FileToken>;

Uploads an audio file with audio-specific metadata. This is a variant of uploadFile used for audio files.

Parameters

Name	Type	Description
data	`Blob`	The binary file data. Usually a File.
metadata	`AudioFileMetadata`	Information about the audio file, see below.

AudioFileMetadata

Property	Type	Description
filename Required	`string`	The name of the file, including the extension.
duration	`number`	The duration of the audio file in seconds, if known.

Returns

A promise that resolves to a FileToken that can be used to send the file in a message.

uploadVoice


1uploadVoice(data: Blob, metadata: VoiceFileMetadata): Promise<FileToken>;

Uploads a voice recording with voice-specific metadata. This is a variant of uploadFile used for voice recordings.

Parameters

Name	Type	Description
data	`Blob`	The binary file data. Usually a File.
metadata	`VoiceFileMetadata`	Information about the audio file, see below.

VoiceFileMetadata

Property	Type	Description
filename Required	`string`	The name of the file, including the extension.
duration	`number`	The duration of the voice recording in seconds, if known.
userRef	`UserRef`	A reference to the user that this session is connected as.

Returns

A promise that resolves to a FileToken that can be used to send the file in a message.

Automatic cleanup

The TalkSession automatically disconnects and reconnects as needed. To fully clean up the TalkSession and release all resources, you should unsubscribe from any active subscriptions, throw away any references to the session, and wait. The session will automatically close its connection to the TalkJS servers, and it will be garbage collected.

You do not need to manually close the TalkSession or do any cleanup.