Create a group chat

You can create a group chat with three or more participants, guests, or both. Participants are members of a conversation, while guests have lightweight guest access. For an overview of the differences between participants and guests, see: Participant access and guest access.

Create a group chat with participants

To create and start a group chat with participants, take the following steps:

  1. Construct a chat session and define the users of your group chat.

For example, the following code constructs a chat session, and defines the users Alice, Sebastian, and Steve:

1await Talk.ready;
2const session = new Talk.Session({
3 appId: '<APP_ID>',
4 userId: '123456',
5});
6
7session.currentUser.createIfNotExists({
8 name: 'Alice',
9 email: '[email protected]',
10});
11
12const other1 = session.user('654321');
13other1.createIfNotExists({
14 name: 'Sebastian',
15 email: '[email protected]',
16});
17
18const other2 = session.user('456789');
19other2.createIfNotExists({
20 name: 'Steve',
21 email: '[email protected]',
22});

You'll need to replace <APP_ID> with your TalkJS App ID. You can find your App ID in the Settings tab of the TalkJS dashboard.

  1. Create a conversation with a unique conversation ID, using the ConversationRef.createIfNotExists method. Optionally set any attributes of the conversation, such as a conversation subject, photo, and custom metadata.
  2. Set the conversation participants using the ParticipantRef.createIfNotExists method.

For example, the following code creates a conversation, sets the three participants that you defined (here identified as me, other1, and other2), and provides a photo URL and a subject for the conversation:

1await Talk.ready;
2...
3const conversation = session.conversation("<CONVERSATION_ID>");
4
5// If the conversation already exists, these properties will not be set.
6// Replace `.createIfNotExists` with `.set` to always set the properties.
7conversation.createIfNotExists({
8 photoUrl: "https://talkjs.com/docs/steel-preserve.jpg",
9 subject: "Beautiful steel preserve for rent!"
10});
11
12// You are added automatically when calling `conversation.createIfNotExists`
13const conversation = session.getOrCreateConversation("<CONVERSATION_ID>");
14conversation.participant(other1).createIfNotExists();
15conversation.participant(other2).createIfNotExists();
16
17const chatbox = session.createChatbox();
18chatbox.select(conversation);
19chatbox.mount(document.getElementById("talkjs-container"));
  • Replace <CONVERSATION_ID> with your own unique conversation ID, which you can choose yourself.

You now have a working example of a group chat with three participants. When you run this code, you should see something like the following:

Loading chat...

Enable guest access to a group chat

If you would like to allow users to access a group chat as a guest, you need to enable guest access for that conversation.

To enable people to join a group chat as guests, take the following steps:

  1. Login to your TalkJS dashboard and go to the Settings tab. Under Security settings, enable browser synchronization of users and conversations by unchecking the following two boxes:
  • Disallow user synchronization via the browser
  • Disallow conversation synchronization via the browser

Unchecking these boxes ensures that data on both users and conversations can be updated via the JavaScript SDK.

  1. In the code where you use the select method to select the active conversation, pass an extra asGuest parameter:
1const conversation = session.conversation('<CONVERSATION_ID>');
2const chatbox = session.createChatbox();
3chatbox.select(conversation, { asGuest: true });

You now have guest access to a group chat enabled.

Note: You cannot join a conversation as a guest if you are already a participant. Specifying asGuest: true has no effect when a user is already a participant of a conversation.

If you would like to switch a current conversation participant’s access type to that of guest, then first delete their "Participant" using conversation.participant(session.currentUser).delete(), then select the conversation as a guest.

For more on guest access, see: Guests.