1-on-1 chat

To make the most of this guide, you will need a TalkJS account.

You'll probably also have an existing app that you want to add TalkJS to.

Add the following script to your app to load TalkJS:

1<!-- minified snippet to load TalkJS without delaying your page -->
2<script>
3(function(t,a,l,k,j,s){
4s=a.createElement('script');s.async=1;s.src='https://cdn.talkjs.com/talk.js';a.head.appendChild(s)
5;k=t.Promise;t.Talk={v:3,ready:{then:function(f){if(k)return new k(function(r,e){l.push([f,r,e])});l
6.push([f])},catch:function(){return k&&new k()},c:l}};})(window,document,[]);
7</script>

Then include this container element in the place in which you want to add your chat:

1<!-- container element in which TalkJS will display a chat UI -->
2<div id='talkjs-container' style='width: 90%; margin: 30px; height: 500px'>
3  <i>Loading chat...</i>
4</div>

Next, we'll view an existing conversation. Add the following code to your app:

1Talk.ready.then(function () {
2  const me = new Talk.User('sample_user_alice');
3  const talkSession = new Talk.Session({
4    appId: '<APP_ID>', // replace with your app ID
5    me: me,
6  });
7
8  const conversation = talkSession.getOrCreateConversation(
9    'sample_conversation'
10  );
11  conversation.setParticipant(me);
12
13  const chatbox = talkSession.createChatbox();
14  chatbox.select(conversation);
15  chatbox.mount(document.getElementById('talkjs-container'));
16});

Let's step through what this code is doing:

• First, we make a connection to the TalkJS servers, known as a session. You'll need to replace <APP_ID> with your own app ID, which you can find on the Settings page of your TalkJS dashboard. For this tutorial, we recommend using the app ID for TalkJS's Test Mode, which has built-in sample users and conversations which we'll use in this tutorial. You'll also need to specify a current user to send messages as. In this example, we've set me to be an existing user, the sample_user_alice sample user. For a user that already exists, we can call the Talk.User constructor with just their user ID.
• Next, we use the getOrCreateConversation method to fetch the existing conversation with an ID of sample_conversation.
• Then we create the chat UI. In this tutorial, we'll create a chatbox UI with the createChatbox method. We use the chatbox's select method to display the sample conversation, and then use the mount method to render the chatbox UI inside the talkjs-container element.

You should see something like this:

Try sending Sebastian a message! You can also try switching your userId to sample_user_sebastian and viewing the other side of the conversation.

If you don't see the chat window, make sure that you entered your app ID, replacing <APP_ID> in the code.

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. Usually, you would create users based on the data from your database. For this getting started guide, we've hard-coded our user data instead.

Modify your previous code by changing the highlighted lines:

1Talk.ready.then(function () {
2      const me = new Talk.User({
3        id: 'nina',
4        name: 'Nina',
5        email: '[email protected]',
6        photoUrl: 'https://talkjs.com/new-web/avatar-7.jpg',
7        welcomeMessage: 'Hi!',
8      });
9      const session = new Talk.Session({
10        appId: '<APP_ID>', // replace with your app ID
11        me: me,
12      });
13      const other = new Talk.User({
14        id: 'frank',
15        name: 'Frank',
16        email: '[email protected]',
17        photoUrl: 'https://talkjs.com/new-web/avatar-8.jpg',
18        welcomeMessage: 'Hey, how can I help?',
19      });
20
21      const conversation = session.getOrCreateConversation('new_conversation');
22      conversation.setParticipant(me);
23      conversation.setParticipant(other);
24
25      const chatbox = session.createChatbox();
26      chatbox.select(conversation);
27      chatbox.mount(document.getElementById('talkjs-container'));
28    });

Here's what we're doing in the updated version:

• We create a new user with an ID of nina to be our current user. As this user is new, we pass the full user object to the Talk.User constructor rather than just the user ID.
• We create a TalkJS session and add our new current user as in the previous section.
• We create a second new user with an ID of frank.
• We use the getOrCreateConversation method to create a new conversation with an ID of new_conversation, and then add the two new users to the conversation with the setParticipant method.
• We create a chatbox, select the conversation and mount the chatbox as in the previous section.

When you mount the chatbox, the new users and conversation are synced with the TalkJS servers.

You should now see something like this:

In this guide, you've added powerful user-to-user chat to your app. You also learned more about the fundamentals of TalkJS, and how it all fits together.

Most importantly, you've built a starting point to try out all the features TalkJS offers. For example, you could create a new UI theme in the Theme Editor, customize your chat with action buttons or HTML panels, or enable email notifications.

For more ideas, try browsing the many examples we offer for different use cases.

Here's what your working example should look like, in full:

1<!doctype html>
2
3<html lang='en'>
4  <head>
5    <meta charset='utf-8' />
6    <meta name='viewport' content='width=device-width, initial-scale=1' />
7
8    <title>TalkJS tutorial</title>
9  </head>
10
11  <!-- minified snippet to load TalkJS without delaying your page -->
12  <script>
13    (function(t,a,l,k,j,s){
14    s=a.createElement('script');s.async=1;s.src='https://cdn.talkjs.com/talk.js';a.head.appendChild(s)
15    ;k=t.Promise;t.Talk={v:3,ready:{then:function(f){if(k)return new k(function(r,e){l.push([f,r,e])});l
16    .push([f])},catch:function(){return k&&new k()},c:l}};})(window,document,[]);
17  </script>
18
19  <script>
20    Talk.ready.then(function () {
21      const me = new Talk.User({
22        id: 'nina',
23        name: 'Nina',
24        email: '[email protected]',
25        photoUrl: 'https://talkjs.com/new-web/avatar-7.jpg',
26        welcomeMessage: 'Hi!',
27      });
28      const session = new Talk.Session({
29        appId: '<APP_ID>', // replace with your app ID
30        me: me,
31      });
32      const other = new Talk.User({
33        id: 'frank',
34        name: 'Frank',
35        email: '[email protected]',
36        photoUrl: 'https://talkjs.com/new-web/avatar-8.jpg',
37        welcomeMessage: 'Hey, how can I help?',
38      });
39
40      const conversation = session.getOrCreateConversation('new_conversation');
41      conversation.setParticipant(me);
42      conversation.setParticipant(other);
43
44      const chatbox = session.createChatbox();
45      chatbox.select(conversation);
46      chatbox.mount(document.getElementById('talkjs-container'));
47    });
48  </script>
49
50  <body>
51    <!-- container element in which TalkJS will display a chat UI -->
52    <div id='talkjs-container' style='width: 90%; margin: 30px; height: 500px'>
53      <i>Loading chat...</i>
54    </div>
55  </body>
56</html>