Large group chat

This guide will help you quickly add TalkJS to your React app and create a large group chat between guest users. Guest access is a lightweight access mode that can scale to larger numbers of users compared to normal participant access. Guests can read and send messages but cannot be mentioned or receive notifications, and they will not appear in the participant list of conversations. See Participant access and guest access for more details.

The guide uses TalkJS's React SDK, which provides pre-built chat UI components for your application.

We'll use it alongside the JavaScript SDK, which we'll use for data manipulation tasks like synchronizing users and conversations.

In the guide we'll walk you through installing TalkJS, viewing an existing conversation, and creating new users and conversations.

You can only allow users to join a large group chat as guests in combination with a chatbox or popup pre-built chat UI, and not with an inbox UI.

Prerequisites

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

  1. A TalkJS account
  2. A basic understanding of React
  3. A React app that you will add TalkJS to

Install TalkJS

To get started, install @talkjs/react along with the regular talkjs package:

1npm install talkjs @talkjs/react

Connect to TalkJS

To use TalkJS in your app, you'll need to create a connection to the TalkJS servers, known as a session.

Our React SDK provides a built-in Session component. Import the Session component in the component where you want to add your chat session:

1import { Session } from '@talkjs/react';

We recommend rendering the session component at the top of your component hierarchy. The connection to the TalkJS servers will live as long as the Session component is mounted, so that it is active even when no chat UI is being shown. This allows you to continue to listen for events or show desktop notifications for new messages.

Next, add the Session component:

1import { Session } from '@talkjs/react';
2
3function Chat() {
4 return <Session appId="<APP_ID>" userId="sample_user_alice"></Session>;
5}
6
7export default Chat;

You'll need to provide the Session component with your TalkJS App ID through the appId prop. You can find your App ID in the Settings tab of the TalkJS dashboard. For this tutorial, we recommend using the App ID for TalkJS's Test Mode, which has built-in sample users and conversations that you can use.

You'll also need to specify a current user to send messages as. In this example, we've used the userId prop to specify the user ID of an existing user, the sample_user_alice sample user.

View an existing conversation as a guest

So far, we have created a connection to the TalkJS servers and added our sample user. Next, we want to create the chat UI and view an existing conversation as a guest user.

TalkJS offers multiple pre-built chat UIs out of the box for your project, including a chatbox and popup UI.

Import your preferred UI component in the component where you want to have your chat UI (this should be a descendant of your Session component so it has access to the connection):

1import { Chatbox } from '@talkjs/react';

Next, add your UI component:

1<Chatbox
2 conversationId="sample_large_group_chat"
3 style={{ width: '100%', height: '500px' }}
4></Chatbox>

You'll need to specify the conversation that you want to view. We'll use the conversationId prop to view a built-in sample conversation with an ID of sample_large_group_chat. For the chatbox and inbox UI, we'll also pass in a style prop with some CSS styling to set the size of the chat.

To specify that we want to add the current user as a guest, we'll set the asGuest prop to true.

Check your browser, and you should see a fully-featured chat window running in your app. For example, for the chatbox that'll look something like this:

Loading chat...

Try sending a message!

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

Create a new user and conversation

So far in this guide we've used a sample user and conversation. Next, we'll create a new user, add them to a conversation as a guest, and sync them with the TalkJS servers.

Let's start with the current user in our session. 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.

We'll use the JavaScript SDK to create the user. To do this, we'll first replace the userId prop in the Session component with the syncUser prop. The syncUser prop takes a callback that creates a Talk.User object:

1import Talk from 'talkjs';
2import { useCallback } from 'react';
3
4function Chat() {
5 const syncUser = useCallback(
6 () =>
7 new Talk.User({
8 id: 'nina',
9 name: 'Nina',
10 email: '[email protected]',
11 photoUrl: 'https://talkjs.com/new-web/avatar-7.jpg',
12 welcomeMessage: 'Hi!',
13 }),
14 []
15 );
16
17 return (
18 <Session appId="<APP_ID>" syncUser={syncUser}>
19 // UI component goes here...
20 </Session>
21 );
22}
23
24export default Chat;

If you sync a User object with the same ID later, any properties that have changed will be updated. Otherwise, if nothing has changed the user stays the same.

Next, we'll sync a new conversation by replacing the conversationId prop in the UI component with the syncConversation prop. This prop takes a callback that uses the JavaScript SDK to create a conversation with getOrCreateConversation. If the conversation ID already exists, TalkJS will load the pre-existing conversation and all previous messages. Otherwise, it creates a new conversation.

In our case, we'll create a conversation with an ID of new_large_group_chat:

1const syncConversation = useCallback((session) => {
2 // JavaScript SDK code here
3 const conversation = session.getOrCreateConversation('new_large_group_chat');
4 return conversation;
5}, []);
6
7// ...
8
9<Chatbox
10 syncConversation={syncConversation}
11 style={{ width: '100%', height: '500px' }}
12 asGuest={true}
13></Chatbox>;

You should see something like this:

Example chat with synced guest user and conversation

Note: If you enable guest access for a conversation, anyone who knows the ID of that conversation can enter that conversation as a guest. To control who gets access to a conversation, use hard-to-guess conversation IDs.

Next steps

In this guide, you've added powerful user-to-user chat to your React 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.

Before you go live, make sure you enable authentication. Authentication keeps your user data secure, by ensuring that only legitimate users can connect to your chat. For details, see: Authentication.

Full code example

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

1import { useCallback } from 'react';
2import Talk from 'talkjs';
3import { Session, Chatbox } from '@talkjs/react';
4
5function Chat() {
6 const syncUser = useCallback(
7 () =>
8 new Talk.User({
9 id: 'nina',
10 name: 'Nina',
11 email: '[email protected]',
12 photoUrl: 'https://talkjs.com/new-web/avatar-7.jpg',
13 welcomeMessage: 'Hi!',
14 }),
15 []
16 );
17
18 const syncConversation = useCallback((session) => {
19 // JavaScript SDK code here
20 const conversation = session.getOrCreateConversation('welcome');
21 return conversation;
22 }, []);
23
24 return (
25 <Session appId="<APP_ID>" syncUser={syncUser}>
26 <Chatbox
27 syncConversation={syncConversation}
28 style={{ width: '100%', height: '500px' }}
29 asGuest={true}
30 ></Chatbox>
31 </Session>
32 );
33}
34
35export default Chat;