Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt

Use this file to discover all available pages before exploring further.

Triggered before the chat sends a message to the agent. Use this event to inspect or modify the message content before it is dispatched to the backend.
For comprehensive guidance on handling user input, see Handling user input.
When you modify messages in the pre:send event, two properties control different aspects of the message: By default, when a user types a message, the same text is used for both LLM processing and UI display. When you modify message.content:
  1. The modified content is sent to the agent for processing.
  2. The UI continues to display the original user input unless you also update display_text.
This separation allows you to transform messages for the agent while preserving what the user sees in the chat interface.

​
Event properties

​
type
string
required
Always 'pre:send'.
​
message
object
required
The message payload to send to the agent. It contains the user’s input and metadata.
​
message.message
object
required
The message object containing the content.
​
message.message.content
string
required
Text content sent to the agent for LLM processing. When you modify this property in the pre:send event handler, the agent receives the modified text, but the user continues to see their original input in the chat UI unless you also update message_state.input.display_text.
​
message.message.message_state
object
State information for the message. Use this object to control what the user sees in the chat UI independently from what the agent receives.
​
message.message.message_state.input.display_text
string
Text displayed to the user in the chat UI. When present, this property takes priority over message.message.content for display purposes. Set this property when you want the user to see different text than what is sent to the agent, for example, showing original input while sending translated text, or displaying a modified version of the message.

​
Examples

The following example demonstrates how to modify message content and add metadata before sending to the agent: 
instance.on('pre:send', (event, instance) => {
    // Log the message payload for debugging purposes
    console.log('About to send message:', event.message);
    
    // Convert message to uppercase before sending
    // This modifies what the agent receives, not what the user sees
    if (event?.message?.message?.content) {
        event.message.message.content = event.message.message.content.toUpperCase();
    }
    
    // Add custom metadata to track message origin and timing
    // This metadata is sent to the agent along with the message
    event.message.metadata = {
        timestamp: Date.now(),
        source: 'web-chat'
    };
});
The following example demonstrates how to translate user messages before sending to the agent while displaying the original text in the UI: 
instance.on('pre:send', async (event, instance) => {
    // Define the user's preferred language
    const userLanguage = 'es'; // User's preferred language
    
    // Only translate if the user's language is not English
    if (userLanguage !== 'en' && event?.message?.message?.content) {
        // Store the original text typed by the user
        const originalText = event.message.message.content;
        
        // Translate the message to English for the agent to process
        // Note: translateText() is a placeholder - implement your own translation service
        const translatedText = await translateText(originalText, userLanguage, 'en');
        
        // Update the content that will be sent to the agent (translated version)
        event.message.message.content = translatedText;
        
        // Store the original text in message_state so the UI displays what the user actually typed
        // This ensures the user sees their original message, not the translated version
        event.message.message.message_state = {
            input: { display_text: originalText }
        };
    }
});

​
Considerations

​
Common patterns

The pre:send event supports several common patterns for handling user input:

Do you need practical examples?

Learn how to apply the features available for embedded chat into your implementation with guidance and examples.