Chat New

The Chat element provides a full chat interface, including a message list with date separators, attachment previews, and a built-in input area for sending messages and uploading files

Features

Complete chat UI: Optional header, message list with grouping and date separators, and a built-in input area
Attachments: Users can attach files; images show previews and other files show name and size
Flexible data mapping: Map your data shape for messages, attachments, and participants
Localization: Configure locale, time format, and relative date labels (today, yesterday, just now)
Header logic: Shows private or group context automatically, with optional close button
Auto-scroll: Control smooth or instant scroll when new messages arrive
Full styling control: Customize header, messages, input area, buttons, icons, and date separators

Getting started

Using AI

The quickest way to set up the chat is by using AI:

Ask AI to add the chat. Be sure to specify:
- your data source for messages and participants
- which participant is the current user
- styling preferences (colors, fonts, rounded corners)
- whether attachments should be enabled
The AI will create a styled chat bound to your data:
Continue refining your chat by asking:
- "Map senderId from my user_id field"
- "Enable smooth auto-scroll on new messages"
- "Make my own messages blue with white text and rounded corners"

Manual setup

Add the Chat element to your page from the Add panel
Bind Participants to an array of users involved in the conversation
Bind Messages to your array of chat messages
In Mapping:
- Set Message mappings (id, text, sender id, timestamp, attachments)
- If you enabled attachments mapping, set attachment field mappings (id, name, url, type, size)
- Set Participant mappings (id, name, avatar, location, status, is current user)
(Optional) Enable Allow attachments if users can upload files
Adjust styling in the Style panel for header, messages, date separator, and input area
(Optional) Configure Locale, Time format, and labels like Today, Yesterday, and just now

Binding messages and participants

In the Settings tab, provide two arrays: Participants and Messages:

If the names of the fields in your data differ to the names expected, you can manually change the mappings:

Participants fields and behavior

Click to view example participants data

json

[
  {
    "id": "u-1",
    "name": "John",
    "avatar": "",
    "status": "online",
    "location": "San Francisco",
    "isCurrentUser": true
  },
  {
    "id": "u-2",
    "name": "Support Assistant",
    "avatar": "https://cdn.weweb-staging-ignis.io/designs/48c20b5b-3c38-442c-b107-606e5f64483f/sections/headshot-assistant.png?_wwcv=1758620031874",
    "status": "online",
    "location": "Paris",
    "isCurrentUser": false
  }
]

ID (required): Unique participant ID. Must match the senderId in your messages.
Name: Shown above the first message in a sequence and used in the header title. Also used for the group header line “Last message from …”.
Avatar URL: Defines the image to show in header.
if there are 2 or fewer different participants (by senderId in messages), the avatar shown at the top-left is the participant whose isCurrentUser is false (i.e., the “other” person in a private chat)

Location: Shown as the secondary line under the name in the header for private chats. In group chats, the header’s secondary line becomes “Last message from …”.

Status: Drives the colored status dot in the header avatar.

Is Current User: Marks the current user. Determines own-message styling and which messages are treated as “yours,” and contributes to header logic (in private chats, the header highlights the other participant).

Messages fields and behavior

Click to view example messages data

json

[
  {
    "id": "m-1",
    "text": "Hi there 👋",
    "senderId": "u-2",
    "timestamp": "2025-09-22T09:00:00Z"
  },
  {
    "id": "m-2",
    "text": "How can I help today?",
    "senderId": "u-2",
    "timestamp": "2025-09-22T09:00:10Z"
  },
  {
    "id": "m-3",
    "text": "I just logged in, I love the platform!.",
    "senderId": "u-1",
    "timestamp": "2025-09-22T09:01:00Z"
  },
  {
    "id": "m-4",
    "text": "Can you share a screenshot?",
    "senderId": "u-2",
    "timestamp": "2025-09-22T09:01:20Z"
  },
  {
    "id": "m-5",
    "text": "Sure, this platform!.",
    "senderId": "u-1",
    "timestamp": "2025-09-22T09:01:40Z",
    "attachments": [
      {
        "id": "att-1",
        "url": "https://cdn.weweb-staging-ignis.io/designs/48c20b5b-3c38-442c-b107-606e5f64483f/sections/weweb-logo-wordmark-black.png?_wwcv=1758617489652",
        "name": "error.png",
        "size": 183221,
        "type": "image/png"
      }
    ]
  },
  {
    "id": "m-6",
    "text": "Thanks! glad you like it.",
    "senderId": "u-2",
    "timestamp": "2025-09-22T09:02:10Z"
  },
  {
    "id": "m-7",
    "text": "Here's a short getting started guide.",
    "senderId": "u-2",
    "timestamp": "2025-09-22T09:02:40Z",
    "attachments": [
      {
        "id": "att-2",
        "url": "https://example.com/files/login-guide.pdf",
        "name": "getting-started.pdf",
        "size": 532188,
        "type": "application/pdf"
      }
    ]
  },
  {
    "id": "m-8",
    "text": "Hey! This conversation will now automatically close",
    "senderId": "u-2",
    "timestamp": "2025-09-23T09:02:10Z"
  }
]

ID (required): Unique message ID
Message Text: The message body shown in the bubble.
Sender ID (required): Must match a participant id. Determines own-message styling and groups consecutive messages from the same sender.
Timestamp: ISO format recommended. Used for the time label on each message, date separators (Today/Yesterday/relative), ordering, and the group header “Last message from …”.
Attachments (optional): Array of attachment objects. Images (type starting with image/) show previews; other files show name and size. Clicking an attachment emits On attachment click.

Attachment fields when attachments are bound:

ID (optional)
Name
URL
Type (MIME)
Size (bytes)

Header behavior

One-to-one chat

In a one-to-one chat, the header shows the other participant’s name, avatar, and optional location/status. The 'other' participant is whichever participant's Is Current User is not true.

Related properties:

Avatar URL (from item in Participants)
Name (from item in Participants)
Location (from item in Participants)
Status (from item in Participants)

Group chat

In a multi-participant chat, it shows a group label. Set a custom Group chat text, or the chat will generate one automatically. The location line can show “Last message from …”.

Props used here:

Group Chat Text
Name (from item in Participants with most recent timestamp)
Group Avatar URL (from item in Participants)

If no Group Avatar URL is defined, then the avatar will default to using the intials of the Group Chat Text:

Sending messages and attachments

To save a message, you need to utilize the On message sent trigger.

Use this pattern to persist messages and keep the chat in sync:

Create a workflow on the chat element using the On message sent trigger.
If any attachments exist in the message, encode them into data URLs so they can be sent to your backend.
Send the message contents and the data URLs of any attachments to your backend for saving.
After a successful response, refetch the data you bound to the chat’s Messages property:
- if Messages is bound to a collection: add a Refetch collection action
- if Messages is bound to a variable: update that variable with the latest server data
(Optional) If you implemented optimistic UI (see below), reconcile with the server response (e.g., replace a temporary id with the saved id).

Optimistic UI

To make messages appear right away after the user presses Send. Bind Messages to a variable and update it immediately so the new message appears instantly. Then, save the message to your backend in the background.

If saving fails, show a clear error and remove (or mark) the temporary message. This approach is called an “optimistic update”. it keeps your chat feeling fast while staying accurate.

Dates, times, and separators

Each day is separated with a date chip (e.g., Today, Yesterday, relative labels, or a formatted date).
Configure:
- Locale (e.g., enUS, fr, de, ja, zhTW, ar, etc.)
- Time format (e.g., h:mm a)
- Today, Yesterday, and Just now labels
Style the date separator’s text, line, background, and radius.

Auto-scrolling

New messages scroll the list to the bottom.
Choose your default behavior with Auto scroll behavior:
- auto: instant jump
- smooth: smooth scrolling
Use the component action Scroll to bottom programmatically. Passing no argument uses the default behavior. Passing true or false forces smooth/instant.

Example use cases

In-app support chat

Create a support chat where users can message your team:

Bind Participants to the current user and the support agent
Bind Messages to your conversation data
Use the On message sent trigger to save new messages

Group team room

Build a team conversation with multiple participants:

Bind Participants to all team members and flag the current user
Bind Messages to the room's messages
Set a custom Group chat text
Use the On message sent trigger to save new messages

Best practices

Do:

localize the chat for your audience with Locale and labels
match senderId in messages to id in participants
handle the saving of messages using the On message sent trigger

Don't:

forget to mark the current user (the chat uses this to style “own” messages)
attach huge files without size checks on the backend

Forking

While the Chat element offers extensive built-in customization options, there may be cases where you need functionality beyond what's natively available. In these situations, you can fork the element and modify it to meet your specific requirements.

If you are unsure how to fork an element, you can learn more in the dedicated documentation.

Properties reference

Chat Settings

Property	Type	Description
Group Chat Text	Text	Custom label for group chats (fallback is auto-generated)
Group Avatar URL	Text	Image URL for the group avatar (optional)
Allow Attachments	Toggle	Allow users to add files when sending messages
Disabled	Toggle	Disable the input and actions
Auto-scroll Behavior	Select	`Instant` or `Smooth` scrolling when new messages arrive

Chat Data

Property	Type	Description
Messages	Array	Collection of messages to display
Message ID	Path/Formula	Field to use as message ID
Message Text	Path/Formula	Field to use as message content
Sender ID	Path/Formula	Field to use as the sender’s ID
Timestamp	Path/Formula	Field to use as the message timestamp
Attachments	Path/Formula	Field to use as attachments (array)

Attachments Data

Property	Type	Description
ID	Path/Formula	Field to use as attachment ID
Name	Path/Formula	Field to use as attachment name
URL	Path/Formula	Field to use as attachment URL
MIME Type	Path/Formula	Field to use as MIME type
Size (bytes)	Path/Formula	Field to use as size in bytes

Participant Data

Property	Type	Description
Participants	Array	Collection of participants in the conversation
ID	Path/Formula	Field to use as participant ID
Name	Path/Formula	Field to use as participant name
Avatar URL	Path/Formula	Field to use as avatar URL
Location	Path/Formula	Field to use as location
Status	Path/Formula	Field to use as status (`online`, `offline`, `away`, `busy`)
Is Current User	Path/Formula	Whether this participant is the current user

Localization

Property	Type	Description
Locale	Select	Date-fns locale key (e.g., `enUS`, `fr`, `de`, `ja`, etc.)
Time Format	Text	Format for message timestamps (e.g., `h:mm a`)
Today Text	Text	Label for today in date separators
Yesterday Text	Text	Label for yesterday in date separators
Just Now Text	Text	Label for very recent times

Styling

General

Property	Description
Font family	Global font for the chat interface

Property	Description
Header background	Header background color
Header text color	Text color in the header
Header border	Border at the bottom of the header
Header padding	Padding inside the header
Header name font size	Font size for the name
Header name font weight	Font weight for the name
Header location font size	Font size for the location line
Header location opacity	Opacity of the location line
Group avatar color	Background color used for group avatar initials
Display Close Button	Show or hide the close icon in the header
Header close button color	Color of the close icon
Header close button hover background	Background on close hover

Messages area

Property	Description
Messages background	Background color of the message list
Messages padding	Inner padding for the message list

Attachment thumbnails (inside messages)

Property	Description
Attachment Max Width	Max width for image attachment previews
Attachment Max Height	Max height for image attachment previews
Attachment Border Radius	Corner radius for image attachment previews

Others’ messages

Property	Description
Message background	Background color of other users’ messages
Message text color	Text color
Message font size	Font size
Message font weight	Font weight
Message font family	Font family
Message border	Border
Message radius	Border radius

Your messages

Property	Description
Message background	Background color of your messages
Message text color	Text color
Message font size	Font size
Message font weight	Font weight
Message font family	Font family
Message border	Border
Message radius	Border radius

Date separator

Property	Description
Date separator text color	Text color
Date separator line color	Line color (left/right lines)
Date separator background	Background behind the label
Date separator border radius	Chip radius

Input area

Property	Description
Input area background	Background color of the input container
Input area border	Top border of the input container
Textarea border	Textarea border
Textarea border hover	Border when hovering
Textarea border focus	Border when focused
Input text color	Text color
Input font size	Font size
Input font weight	Font weight
Input font family	Font family
Input placeholder color	Placeholder color
Input height	Fixed height of the textarea
Input border radius	Textarea radius

Icons and buttons

Property	Description
Send icon	Icon name for send
Send icon color	Color of send icon
Send icon size	Size of send icon
Attachment icon	Icon name for attachment
Attachment icon color	Color of attachment icon
Attachment icon size	Size of attachment icon
Remove icon	Icon name for removing a pending attachment
Remove icon color	Color of remove icon
Remove icon size	Size of remove icon
Send button background	Background/gradient of send button
Send button hover background	Background/gradient on hover
Send button border	Border
Send button border radius	Radius
Send button size	Width/height
Send button box shadow	Shadow
Attachment button background	Background of attachment button
Attachment button hover background	Hover background
Attachment button border	Border
Attachment button border radius	Radius
Attachment button size	Width/height
Attachment button box shadow	Shadow

Empty state

Property	Description
Empty message text	Text shown when there are no messages
Empty message color	Color for the empty message

Component actions

Action	Description	Parameters
Scroll to bottom	Scrolls to the latest message	`smooth` (Boolean, optional). If omitted, uses `Auto scroll behavior`.

Exposed variables

This element exposes the following variable automatically:

Variable	Type	Description
chatState	Object	Complete chat state including messages, conversation, current user, and utils

Example variable values

chatState

javascript

{
  "messages": [
    {
      "id": "msg-101",
      "text": "Welcome!",
      "senderId": "agent-1",
      "userName": "Support",
      "timestamp": "2025-09-18T14:22:10.123Z",
      "attachments": [
        { "id": "file-1", "name": "guide.pdf", "url": "https://...", "type": "application/pdf", "size": 532188 }
      ],
      "userSettings": {
        "userName": "Support",
        "userAvatar": "https://...",
        "userLocation": "",
        "userStatus": "online"
      }
    }
  ],
  "conversation": {
    "type": "private",
    "participantCount": 2,
    "otherParticipantCount": 1,
    "participants": [
      { "id": "agent-1", "name": "Support", "avatar": "https://...", "location": "", "status": "online", "lastMessageTime": "2025-09-18T14:22:10.123Z" }
    ],
    "allParticipants": [
      { "id": "me-1", "name": "You", "avatar": "", "location": "", "status": "online", "isCurrentUser": true, "lastMessageTime": null },
      { "id": "agent-1", "name": "Support", "avatar": "https://...", "location": "", "status": "online", "isCurrentUser": false, "lastMessageTime": "2025-09-18T14:22:10.123Z" }
    ]
  },
  "currentUser": { "id": "me-1", "name": "You", "avatar": "", "location": "", "status": "online" },
  "utils": { "messageCount": 1, "isDisabled": false, "allowAttachments": true, "displayHeader": true }
}

Event triggers

Event	Description	Payload
messageSent	Fired when the user sends a message	`{ message }`
messageReceived	Fired when a new message appears in `messages` from another sender	`{ message }`
messageRightClick	Fired on right-click on a message	`{ message, position: { elementX, elementY, viewportX, viewportY } }`
attachmentClick	Fired when an attachment is clicked	`{ attachment }`
pendingAttachmentClick	Fired when a pending (unsent) attachment is clicked	`{ attachment: File, index }`
close	Fired when the header close button is clicked	`{}`

Example event payloads

messageSent

javascript

{
  "message": {
    "id": "msg-7f3a",
    "text": "Got it, thanks!",
    "senderId": "me-1",
    "userName": "You",
    "timestamp": "2025-09-19T10:15:00.000Z",
    // attachments is an array of File objects when present
    "attachments": [ /* File */ ]
  }
}

messageReceived

javascript

{
  "message": {
    "id": "msg-7f3b",
    "text": "Happy to help!",
    "senderId": "agent-1",
    "userName": "Support",
    "timestamp": "2025-09-19T10:15:05.000Z",
    "attachments": [
      { "id": "file-9", "name": "guide.pdf", "url": "https://...", "type": "application/pdf", "size": 532188 }
    ],
    "userSettings": { "userName": "Support", "userAvatar": "https://...", "userLocation": "", "userStatus": "online" }
  }
}

messageRightClick

javascript

{
  "message": {
    "id": "msg-7f3a",
    "text": "Got it, thanks!",
    "senderId": "me-1",
    "timestamp": "2025-09-19T10:15:00.000Z"
  },
  "position": { "elementX": 120, "elementY": 24, "viewportX": 320, "viewportY": 480 }
}

The elementX and elementY is the position relative to the chat element, and the viewportX and viewportY is the position relative to the page.

attachmentClick

javascript

{
  "attachment": {
    "id": "file-9",
    "name": "guide.pdf",
    "url": "https://...",
    "type": "application/pdf",
    "size": 532188
  }
}

pendingAttachmentClick

javascript

{
  "attachment": File, // The underlying File object of the pending upload
  "index": 0
}

close

javascript

{}

Chat New ​

Features ​

Getting started ​

Using AI ​

Manual setup ​

Binding messages and participants ​

Participants fields and behavior ​

Messages fields and behavior ​

Header behavior ​

One-to-one chat ​

Group chat ​

Sending messages and attachments ​

Dates, times, and separators ​

Auto-scrolling ​

Example use cases ​

In-app support chat ​

Group team room ​

Best practices ​

Do: ​

Don't: ​

Forking ​

Properties reference ​

Chat Settings ​

Chat Data ​

Attachments Data ​

Participant Data ​

Localization ​

Styling ​

General ​

Header ​

Messages area ​

Attachment thumbnails (inside messages) ​

Others’ messages ​

Your messages ​

Date separator ​

Input area ​

Icons and buttons ​

Empty state ​

Component actions ​

Exposed variables ​

Example variable values ​

Event triggers ​

Example event payloads ​

messageSent ​

messageReceived ​

messageRightClick ​

attachmentClick ​

pendingAttachmentClick ​

close ​

Chat New

Features

Getting started

Using AI

Manual setup

Binding messages and participants

Participants fields and behavior

Messages fields and behavior

Header behavior

One-to-one chat

Group chat

Sending messages and attachments

Dates, times, and separators

Auto-scrolling

Example use cases

In-app support chat

Group team room

Best practices

Do:

Don't:

Forking

Properties reference

Chat Settings

Chat Data

Attachments Data

Participant Data

Localization

Styling

General

Header

Messages area

Attachment thumbnails (inside messages)

Others’ messages

Your messages

Date separator

Input area

Icons and buttons

Empty state

Component actions

Exposed variables

Example variable values

Event triggers

Example event payloads

messageSent

messageReceived

messageRightClick

attachmentClick

pendingAttachmentClick

close