Getting started

This guide will help you quickly add TalkJS to your web app and create a chat between two users, using TalkJS Web Components. These are highly customizable chat UI components, which work with any modern web framework, but also without any framework at all. We'll use it alongside the JavaScript Data API, which we'll use for data manipulation tasks like synchronizing users and conversations.

This guide shows how to use TalkJS without a JS package manager (like npm) and without a frontend build tool (like Vite or Webpack). We'll walk you through including our libraries in your HTML <head> tag, viewing an existing conversation, creating new users and conversations, customizing the UI, and properly securing it all.

Prerequisites

To make the most of this guide, you will need:

A TalkJS account
A website or app to which you'd like to add TalkJS chat

Installation

Begin by importing TalkJS components and your theme. To import your components and theme, add the following inside the <head> of the HTML page to which you would like to load your chat:


1<link
2  rel="stylesheet"
3  href="https://cdn.jsdelivr.net/npm/@talkjs/[email protected]/default.css"
4/>
5<script
6  src="https://cdn.jsdelivr.net/npm/@talkjs/[email protected]"
7  async
8></script>

View a conversation

To view a sample conversation, add the chatbox to the page to which you'd like to add chat:


1<div style="width: 400px; height: 600px">
2  <t-chatbox
3    id="chat"
4    app-id="<APP_ID>"
5    user-id="sample_user_alice"
6    conversation-id="sample_conversation"
7  ></t-chatbox>
8</div>

This t-chatbox web component has the following attributes:

app-id: Your TalkJS app ID. You can find your app ID on the Settings page of your TalkJS dashboard. For this guide, use the app ID for your test mode, which has built-in sample users and conversations.

user-id: An identifier for the current user to send messages as. This example uses the ID of an existing sample user, sample_user_alice.
conversation-id: An identifier of the conversation that you want to view. This example uses the ID for a built-in sample conversation, sample_conversation.

We've also given it an id attribute, which we'll use later to select it when we want to update the values of other attributes.

The chatbox is wrapped in a divider that applies CSS styling to set the size of the chatbox. You can modify the size to suit your needs.

Open the page in your browser. You should get something like the following:

Chatbox showing a message from Sebastian

You now have a fully-featured chat window running in your app. Try sending a message!

To view the conversation as a different user, change the user-id. For example, try switching the user-id to sample_user_sebastian to view the other side of the sample conversation.

If you don't see the chat window, make sure that you've entered your app ID correctly.

Create new users and conversations

So far in this guide we've used a sample user and conversation. Next, we'll create new users and a conversation between them, and sync them with the TalkJS servers. To do this, we'll use the JavaScript Data API.

Update your <t-chatbox> to look like this:


1<t-chatbox
2  id="chat"
3  app-id="<APP_ID>"
4  user-id="frank"
5  conversation-id="my_conversation"
6></t-chatbox>

Add the following code to the head tag of your page:


1<script type="module">
2  import { getTalkSession } from 'https://cdn.jsdelivr.net/npm/@talkjs/[email protected]';
3
4  const appId = '<APP_ID>';
5
6  const userId = 'frank';
7  const otherUserId = 'nina';
8  const conversationId = 'my_conversation';
9
10  const session = getTalkSession({ appId, userId });
11
12  session.currentUser.createIfNotExists({ name: 'Frank' });
13  session.user(otherUserId).createIfNotExists({ name: 'Nina' });
14
15  const conversation = session.conversation(conversationId);
16  conversation.createIfNotExists();
17  conversation.participant(otherUserId).createIfNotExists();
18</script>

As before, replace <APP_ID> with your TalkJS app ID.

This code creates a new TalkJS session, which provides access to a continuous, up-to-date flow of your TalkJS data. It then creates two new users and a conversation between them.

Code example

Here's the code so far, so that you can see how it all fits together:


1<html lang="en">
2  <head>
3    <meta charset="UTF-8" />
4    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
5    <title>TalkJS components tutorial</title>
6
7    <link
8      rel="stylesheet"
9      href="https://cdn.jsdelivr.net/npm/@talkjs/[email protected]/default.css"
10    />
11    <script
12      src="https://cdn.jsdelivr.net/npm/@talkjs/[email protected]"
13      async
14    ></script>
15    <script type="module">
16      import { getTalkSession } from 'https://cdn.jsdelivr.net/npm/@talkjs/[email protected]';
17
18      const appId = '<APP_ID>';
19
20      const userId = 'frank';
21      const otherUserId = 'nina';
22      const conversationId = 'my_conversation';
23
24      const session = getTalkSession({ appId, userId });
25
26      session.currentUser.createIfNotExists({ name: 'Frank' });
27      session.user(otherUserId).createIfNotExists({ name: 'Nina' });
28
29      const conversation = session.conversation(conversationId);
30      conversation.createIfNotExists();
31      conversation.participant(otherUserId).createIfNotExists();
32    </script>
33  </head>
34  <body>
35    <div style="width: 400px; height: 600px">
36      <t-chatbox
37        id="chat"
38        app-id="<APP_ID>"
39        user-id="frank"
40        conversation-id="my_conversation"
41      ></t-chatbox>
42    </div>
43  </body>
44</html>

Customizing TalkJS

The easiest way to customize TalkJS's components, is using the properties and events that the components expose. See each component’s reference documentation for a list of available properties and events.

As an example, if you want to hide the built-in chat header, because it doesn't work well with the rest of your UI, you'd render the chatbox like this:


1<t-chatbox
2  id="chat"
3  app-id="<APP_ID>"
4  user-id="frank"
5  conversation-id="my_conversation"
6></t-chatbox>
7<script>
8  // We can't pass values that aren't strings to the chatbox as attributes,
9  // so we need to set it as a property using JavaScript.
10  const chatbox = document.getElementById('chat');
11  chatbox.chatHeaderVisible = false;
12</script>

If you need even more flexibility, TalkJS has an extensive theme system, which lets you adapt the styles, markup and behavior of the entire chat UI. See the Customization guide for more details.

Add authentication

Once you're using TalkJS in production you'll need to enable authentication, so that only legitimate users can connect to your chat. You'll need a backend server that can generate tokens for your users to authenticate with. See our Authentication docs for more detail on how to set this up.

To pass the token to your chatbox, add the token attribute:


1<t-chatbox
2  id="chat"
3  app-id="<APP_ID>"
4  user-id="frank"
5  conversation-id="my_conversation"
6  token="token"
7></t-chatbox>

You also need to pass the token to your session:


1const session = getTalkSession({ appId, userId, token });

The token is different each time you connect to TalkJS, so you'll need to call your backend to generate it.

Once you are happy that your chat is loading without errors when you provide a token, go the the Settings page of your dashboard and enable the Authentication (identity verification) option in the Security settings section. When authentication is enabled, only users with a valid token can connect to your chat.

Next steps

For more ways to customize your chat, see our Chatbox reference docs.