Welcome messages

View as Markdown

Welcome messages are pre-written messages that appear at the top of a conversation before any real messages are sent. They are a common pattern in marketplace and support apps — for example, a seller greeting a potential buyer when they open a chat for the first time.

Welcome messages are purely visual and they are not stored in the conversation as real message objects.

Conversation welcome messages

The simplest way to show welcome messages is to set welcomeMessages on the conversation object. Set this field via the Data API or the REST API. The default <BeforeMessages> theme component shows these automatically as virtual system messages.

For example:

1import { getTalkSession } from "@talkjs/core";
2

3const session = getTalkSession({ appId: "<APP_ID>", userId: "betty_buyer" });
4session.conversation("my_conversation").createIfNotExists({
5  welcomeMessages: ["You are chatting with a verified seller."],
6});

Custom welcome messages

For more control, override your theme's <BeforeMessages> component and use <VirtualMessage>. For example, this lets you attribute a message to a specific user (showing their name and avatar), or to use rich text formatting.

Virtual messages are purely visual and are never stored or sent through TalkJS.

Single message

The following shows a welcome message attributed to a seller:

1import { Chatbox, VirtualMessage } from "@talkjs/react-components";
2import "@talkjs/react-components/default.css";
3

4const theme = {
5  BeforeMessages: () => (
6    <VirtualMessage
7      text="Hi! Let me know if you have any questions about this item."
8      sender="pete_seller"
9    />
10  ),
11};
12

13export function Chat() {
14  return (
15    <Chatbox
16      appId="<APP_ID>"
17      userId="betty_buyer"
18      conversationId="my_conversation"
19      theme={theme}
20    />
21  );
22}

Setting sender to the seller's user ID causes the message to appear as if it came from that user, complete with their name and avatar. Omitting sender renders the message as a system message instead.

Multiple messages

When rendering more than one <VirtualMessage>, you need to list them in reverse order in the DOM. This is because the message list uses flex-direction: column-reverse to keep the newest messages anchored at the bottom.

Additionally, when rendering multiple virtual messages from the same sender, we recommend you wrap them in a <div className="t-message-group"> so that the default CSS for grouping behavior (eg spacing, avatar visibility, etc.) applies correctly.

For example:

1import { Chatbox, VirtualMessage } from "@talkjs/react-components";
2import "@talkjs/react-components/default.css";
3

4const theme = {
5  BeforeMessages: () => (
6    <div className="t-message-group">
7      <VirtualMessage
8        text="Feel free to ask about pricing or availability!"
9        sender="pete_seller"
10      />
11      <VirtualMessage
12        text="Hi! Thanks for your interest in my shop."
13        sender="pete_seller"
14      />
15    </div>
16  ),
17};
18

19export function Chat() {
20  return (
21    <Chatbox
22      appId="<APP_ID>"
23      userId="betty_buyer"
24      conversationId="my_conversation"
25      theme={theme}
26    />
27  );
28}