<VirtualMessage>

View as Markdown

The <VirtualMessage> system component renders a fake message that looks and behaves like a real chat message, but is never stored or sent through TalkJS. It is useful for showing contextual prompts such as welcome messages at the top of a conversation.

Place <VirtualMessage> inside <BeforeMessages> so that it appears above the real messages and scrolls with the message list.

If you only need plain system messages, the simplest approach is to set conversation.welcomeMessages on the conversation object — the default <BeforeMessages> renders these automatically. Use <VirtualMessage> directly when you need more control, such as attributing a message to a specific user or using rich text formatting.

Internally, <VirtualMessage> uses the provided props to compose a complete MessageSnapshot object, which is then passed to the Message component from your theme.

interface VirtualMessageProps

Properties

content (optional)

: ContentBlock[]

The content of the message as a content block.

Lets you precisely control the formatting of the message, see Message content. Specify either text or content, but not both.

createdAt (optional)

: number

Override the message's timestamp

Defaults to -1, which our preset themes interpret as "do not show a timestamp at all"

custom (optional)

: Record<string, string>

Custom data for the message object.

You can read this out in message.custom inside the Message theme component.

sender (optional)

: string | UserSnapshot

The ID of the sender of this message, or a complete UserSnapshot with the sender's details.

When omitted, the message is rendered as a system message.

When passing a UserSnapshot, this object is used in full and the user is not loaded from the database, which means that you can also pass a fake user that does not really exist.

status (optional)

: MessageStatus

Control the message's delivery status

Defaults to "virtual", which make our preset themes not render status ticks at all. Set it to eg "sent" to show a tickmark, or to "everyoneRead" to show a double tickmark.

text (optional)

: string

The text of the message. Accepts formatting markup like the chatbox message field does, eg *this* would become bold.

Specify either text or content, but not both.

Example

The following example shows a welcome message from a seller, rendered before the real messages:


1import { html, VirtualMessage } from "@talkjs/web-components";
2/** @import { BeforeMessagesProps } from "@talkjs/web-components"; */
3
4/** @param {BeforeMessagesProps} props */
5export function BeforeMessages() {
6  return html`
7    <${VirtualMessage}
8      text="Hi! Let me know if you have any questions about this item."
9      sender="seller_user_id"
10    />
11  `;
12}

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.

For a complete integration example, including how to handle multiple virtual messages, see the Welcome messages guide.