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.

Conversaton welcome messages

The simplest way to show welcome messages is to set welcomeMessages on the conversation object, via the Data API or the REST API. The default <BeforeMessages> theme component renders these automatically as 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 { html, VirtualMessage } from "@talkjs/web-components";
2import "@talkjs/web-components/default.css";
3
4const theme = {
5  BeforeMessages: () => html`
6    <${VirtualMessage}
7      text="Hi! Let me know if you have any questions about this item."
8      sender="pete_seller"
9    />
10  `,
11};

Then, set your <t-chatbox> element's theme property to theme.

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 class="t-message-group"> so that the default CSS for grouping behavior (eg spacing, avatar visibility, etc.) applies correctly.

For example:


1import { html, VirtualMessage } from "@talkjs/web-components";
2import "@talkjs/web-components/default.css";
3
4const theme = {
5  BeforeMessages: () => html`
6    <div class="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};

Then, set your <t-chatbox> element's theme property to theme.