Getting started

To make the most of this guide, you'll need:

• A TalkJS account
• A Vue app to which you'd like to add TalkJS chat

To get started, install @talkjs/web-components:

1npm install @talkjs/web-components

To use TalkJS's web components, you'll need to configure Vue to resolve them. If you use Vite to build your project, you can do this by updating your vite.config.js file to treat components with a - in their name as custom elements:

1import vue from '@vitejs/plugin-vue';
2
3export default {
4  plugins: [
5    vue({
6      template: {
7        compilerOptions: {
8          // treat all tags with a dash as custom elements
9          isCustomElement: (tag) => tag.includes('-'),
10        },
11      },
12    }),
13  ],
14};

For other configuration options, see Vue's docs on Using custom elements in Vue.

You now have TalkJS components installed.

To view an existing sample conversation, import the components and theme into your app, for example in the App.vue file:

1<script setup>
2  import '@talkjs/web-components';
3  import '@talkjs/web-components/default.css';
4</script>

Next, add the t-chatbox web component and styling:

1<script setup>
2  import '@talkjs/web-components';
3  import '@talkjs/web-components/default.css';
4
5  const appId = '<APP_ID>';
6</script>
7
8<template>
9  <main>
10    <div class="wrapper">
11      <t-chatbox
12        :app-id="appId"
13        user-id="sample_user_alice"
14        conversation-id="sample_conversation"
15      />
16    </div>
17  </main>
18</template>
19
20<style scoped>
21  .wrapper {
22    width: 400px;
23    height: 600px;
24  }
25</style>

The t-chatbox component has the following attributes:

• appId: 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.

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

Run your app. You should get something like the following:

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 userId. For example, try switching the userId to sample_user_sebastian to view the other side of the sample conversation.

If the chat window doesn't show up, make sure that you've entered your app ID correctly.

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.

Install the @talkjs/core package:

1npm install @talkjs/core

Then import getTalkSession from the package into your component:

1<script setup>
2  import '@talkjs/web-components';
3  import '@talkjs/web-components/default.css';
4  import { getTalkSession } from '@talkjs/core';
5</script>

Add the following code to the script section of your component:

1const userId = 'frank';
2const otherUserId = 'nina';
3const conversationId = 'my_conversation';
4
5const session = getTalkSession({ appId, userId });
6session.currentUser.createIfNotExists({ name: 'Frank' });
7session.user(otherUserId).createIfNotExists({ name: 'Nina' });
8
9const conversation = session.conversation(conversationId);
10conversation.createIfNotExists();
11conversation.participant(otherUserId).createIfNotExists();

Update the t-chatbox component in your template to use the new variables:

1<t-chatbox
2  :app-id="appId"
3  :user-id="userId"
4  :conversation-id="conversationId"
5/>

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.

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

1<script setup>
2  import '@talkjs/web-components';
3  import '@talkjs/web-components/default.css';
4  import { getTalkSession } from '@talkjs/core';
5
6  const appId = '<APP_ID>';
7  const userId = 'frank';
8  const otherUserId = 'nina';
9  const conversationId = 'my_conversation';
10
11  const session = getTalkSession({ appId, userId });
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>
19
20<template>
21  <main>
22    <div class="wrapper">
23      <t-chatbox
24        :app-id="appId"
25        :user-id="userId"
26        :conversation-id="conversationId"
27      />
28    </div>
29  </main>
30</template>
31
32<style scoped>
33  .wrapper {
34    width: 400px;
35    height: 600px;
36  }
37</style>

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

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    :app-id]="appId"
3    :user-id="userId"
4    :conversation-id="conversationId"
5    :chat-header-visible="false"
6  />

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.

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 prop:

1<t-chatbox
2  :app-id="appId"
3  :user-id="userId"
4  :conversation-id="conversationId"
5  :theme="customTheme"
6  :token="token"
7/>

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.

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