When Chat Message Received
Description
Use the When Chat Message Received trigger activity to start a conversational workflow when a user sends a chat message.
This trigger activity is primarily used together with the Conversational Agent activity to build AI-powered chat and voice experiences in IB-X.
The trigger listens for incoming conversation requests from supported communication channels and starts the workflow execution automatically.
- This activity is a trigger activity and must be placed at the beginning of the workflow.
- The activity is intended for conversational and chat-based workflows.
- Session behavior may vary depending on the configured communication channel.
- The trigger works together with the Conversational Agent activity to build conversational experiences.
Usage
The When Chat Message Received trigger is commonly used for:
- AI chatbots
- Conversational assistants
- Support chat workflows
- Knowledge assistants
- AI voice assistants
- Multi-turn conversational experiences
This activity must be used as the starting point of the conversational workflow.
Workflow Structure
Typical workflow:
The trigger receives the incoming message and passes the conversation context to the Conversational Agent activity.
Customize Chat Experience
To customize the behavior and appearance of your conversational agent, double-click the When Chat Message Received trigger activity on the designer canvas.
The trigger configuration allows you to configure the chat interface, voice settings, and conversation behavior for the agent.
The configuration is organized into the following sections:
- AI Persona
- Welcome
- Greeting
- Features
- Voice
- Transcriber
- Advanced
- Embed
Appearance
Use the Appearance section to customize the visual identity of the conversational agent.
Avatar of your Agent
Select the avatar image that represents the conversational agent.
The selected avatar is displayed in:
- Chat conversations
- Greeting messages
- Voice assistant view
- Floating assistant widget
Theme Color of Chat Window
Specify the primary color theme for the chat window.
The selected color is applied to:
- Chat headers
- Accent elements
- Action buttons
- Avatar highlights
Welcome
Use the Welcome section to configure the initial behavior and appearance of the chat widget.
Greeting
Enable or disable the welcome greeting message.
When enabled, the configured greeting message is automatically displayed when the chat widget opens.
Welcome Message
Specify the initial greeting text displayed to the user.
Example:
Hi! How can I assist you today?
Open by Default
Specify how the chat window should behave when the page initially loads.
You can choose whether the chat window remains minimized, opens immediately, or automatically expands after a short delay.
| Option | Description |
|---|---|
| Do not open automatically | The chat window remains minimized when the page loads and must be manually opened by the user. |
| Always open | The chat window automatically opens in expanded mode when the page loads. |
| Open after 5 seconds | The chat window remains minimized initially and automatically expands 5 seconds after the page loads. |
| Open after 10 seconds | The chat window remains minimized initially and automatically expands 10 seconds after the page loads. |
Avatar Size
Specify the display size of the AI agent avatar within the chat window.
| Option | Description |
|---|---|
| Small | Displays a compact avatar suitable for minimal chat window space usage. |
| Medium | Displays the avatar with a balanced size suitable for most conversational interfaces. |
| Large | Displays a larger avatar to provide stronger visual presence within the chat interface. |
Position
Specify the screen position where the conversational widget should appear.
| Option | Description |
|---|---|
| Left | Displays the conversational widget on the left side of the screen. |
| Right | Displays the conversational widget on the right side of the screen. |
Pulsing
Enable or disable pulsing animation for the avatar.
This effect helps draw user attention to the conversational assistant.
Greeting
Use the Greeting section to configure how the conversation starts.
First Message Mode
Specify how the conversation should begin when the chat session starts.
| Option | Description |
|---|---|
| Agent speaks first | The conversational agent automatically starts the conversation using the configured greeting message. |
| Agent waits for user | The conversational agent waits for the user to send the first message before responding. |
| Agent speaks first with AI generated message | The conversational agent automatically starts the conversation with a dynamically AI-generated greeting based on the configured instructions and conversation context. |
Greeting Message
Specify the greeting message that should be displayed or spoken when the conversation starts.
This message is used when the selected First Message Mode allows the agent to initiate the conversation.
Sample greeting message:
Hello! I'm Lily, your AI Agent for knowledge improvement. How may I assist you today?
Features
Use the Features section to enable or disable conversational capabilities.
Chat
Enable or disable text chat functionality.
Voice
Enable or disable voice conversation capability.
File Attachments
Enables or disables file attachments in the chat window.
When enabled, the chat window displays an Attach File option, allowing end users to upload one or more files as part of a conversation. Attached files are sent along with the user's message and can be processed by the Conversational Agent.
When disabled, the attachment option is hidden from the chat window.
Default: Enabled
The attachment option is displayed only when the configured AI model and provider support file attachments. If attachments are not supported, the option remains hidden even when this setting is enabled.
Download Conversation
Enables or disables the ability for end users to download their conversation from the chat window.
When enabled, users can export the conversation from the chat window menu in one of the following formats:
| Format | Description |
|---|---|
| TXT | Plain-text conversation transcript |
| JSON | Structured conversation including message metadata |
When disabled, the download option is not displayed in the chat window.
Default: Disabled
This setting controls only the ability to download the conversation transcript. It does not affect downloading files that were shared as part of the conversation.
Embed
The Embed section provides the URLs and configuration required to integrate the conversational agent with external websites, portals, and third-party applications.
Chat URL (Testing)
Displays the testing URL for the conversational agent.
Use this URL during development and validation to test the latest version of the conversational experience before using the production endpoint.
You can:
- Open the testing chat in a new browser tab.
- Copy the testing URL.
Chat URL (Production)
Displays the production URL for the conversational agent.
Use this URL when the conversational agent is ready for production use or for embedding into customer-facing websites and applications.
You can:
- Open the production chat in a new browser tab.
- Copy the production URL.
Embed Script
Provides the JavaScript snippet required to embed the chat widget into an external website or web application.
Copy the generated script and paste it into the HTML page where the chat widget should appear.
The embed script automatically connects the widget to the configured conversational agent.
If required, additional context such as user information, page URL, or custom data can also be supplied to the embedded widget.
Authentication
Configures authentication requirements for accessing the conversational agent.
Use this section when requests to the chat endpoint must be authenticated before users are allowed to start a conversation.
Click Add to configure one or more authentication providers or credentials.
Security
Use the Security section to configure access restrictions for the Conversational Agent, such as limiting access to whitelisted IP addresses.
IP Whitelist
Restricts access to the chat endpoint based on the client's IP address.
Click Add IP Address to specify one or more allowed IP addresses.
Supported formats include:
- IPv4 addresses
- IPv6 addresses
- CIDR ranges
- Requests originating from IP addresses outside the configured whitelist are rejected with 403 Forbidden.
- If no IP addresses are configured, the chat endpoint accepts requests from any IP address.
Allowed Origins (CORS)
Specifies which browser origins are permitted to access the chat endpoint through Cross-Origin Resource Sharing (CORS).
Click Add Origin to configure one or more allowed origins.
Supported values include:
- Individual website origins
- Comma-separated lists of origins
*to allow all origins
If the chat widget is embedded into an external website, add that website's origin to allow browsers to communicate with the chat endpoint.
This setting applies only to browser-based requests. It does not restrict server-to-server requests.
Outputs
The When Chat Message Received trigger activity produces the following outputs, which can be consumed by downstream conversational and workflow activities.
SessionId
Represents the unique identifier associated with the active conversation session.
The SessionId is used to:
- Maintain conversational continuity
- Associate multiple messages with the same conversation
- Preserve conversation memory and context
- Track user interactions across the session lifecycle
The Conversational Agent activity uses the SessionId to maintain and retrieve conversation history for the active session.
Chat Message
Represents the incoming user message received by the conversational trigger.
This output contains the text message provided by the user and is typically consumed by the Conversational Agent activity for response generation.
Context
Represents the contextual information associated with the current conversation request.
The context may include:
- Conversation metadata
- User-specific information
- Session-level variables
- Custom contextual data
- Channel-related information
This output helps maintain contextual awareness across conversational interactions.
Attached Files
Represents the files uploaded by the user as part of a chat message.
This output contains the files the user attached and sent in the conversation. It does not include conversation export downloads (TXT or JSON) initiated from the chat window download menu.
Files are uploaded when the user selects them in the chat composer, before the message is sent. Upload requires an active conversation session. Once uploaded, the files are associated with the user's message and passed to downstream workflow activities.
When a user sends a message with attachments, the platform also passes attachment file identifiers to the conversational pipeline so the Conversational Agent can include the uploaded files in its reasoning context.
This output can be used for scenarios such as:
- Document analysis
- Image processing
- File-based AI interactions
- Knowledge extraction workflows
- Attachment validation or storage
Multiple files may be included depending on the client capabilities and conversation flow.
Conversation Flow
When a user sends a message:
- The trigger receives the incoming message.
- A conversation session is created or resumed.
- The conversation context is initialized.
- The workflow execution starts.
- The message and context are passed to the Conversational Agent activity.
Best Practices
- Use this trigger only for conversational workflows.
- Configure appropriate session timeout values.
- Enable conversation history for multi-turn conversations.
- Ensure the trigger is connected to a Conversational Agent activity.
- Enable Download conversation only when end users need to export conversation records or download tool responses.
- Disable File attachments when the agent does not require file input or when the configured model does not support attachments.
- Use meaningful display names for easier maintenance.