JavaScript with no framework

Preview

Components v2 is under development, but already safe to use in production.

It currently only offers limited features. Only the chatbox chat UI is currently available, not the inbox or popup. New capabilities are added on a rolling basis.

Components v2 provides web components for your chat UI. The recommended way of using Components v2 is to install it with a package manager. This gives full control over the appearance and behavior of your chat.

If you use JavaScript without a build step or framework and this is not possible, follow this guide to get started. We'll walk you through how to include our libraries in your HTML <head> tag, view a conversation, and edit the theme CSS to style your chat. If you want to edit the chat UI components themselves to customize the behavior of your chat, you will need to use a package manager instead. See our framework-specific getting started guides for help with getting set up.

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/components@0.0.3/dist/style.standalone.css"
4/>
5<script
6  src="https://cdn.jsdelivr.net/npm/@talkjs/components@0.0.3"
7  async
8></script>

These scripts instruct the browser to find any additional dependencies, and import the logic for components as well as your theme.

With TalkJS components and a theme installed, you can now view an existing sample conversation.

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 TalkJS Core.

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 { TalkSession } from 'https://cdn.jsdelivr.net/npm/@talkjs/core@0.0.2';
3
4  const appId = '<APP_ID>';
5
6  const userId = 'frank';
7  const otherUserId = 'nina';
8  const conversationId = 'my_conversation';
9
10  const session = new TalkSession({ 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/components@0.0.3/dist/style.standalone.css"
10    />
11    <script
12      src="https://cdn.jsdelivr.net/npm/@talkjs/components@0.0.3"
13      async
14    ></script>
15    <script type="module">
16      import { TalkSession } from 'https://cdn.jsdelivr.net/npm/@talkjs/core@0.0.2';
17
18      const appId = '<APP_ID>';
19
20      const userId = 'frank';
21      const otherUserId = 'nina';
22      const conversationId = 'my_conversation';
23
24      const session = new TalkSession({ 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>

Style your chat

For example, to give the message field a different background color, add the following code to your HTML to set the message field to light blue:


1<style>
2  .t-theme-message-field .t-wrapper {
3    background-color: lightblue;
4  }
5</style>

Chatbox with a light blue message field

If you want to edit the chat UI components themselves to change the behavior of your chat, you will need to install Components v2 with a package manager. See our framework-specific getting started guides 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 = new TalkSession({ 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.