> ## 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.

# pre:send

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.

<Note>
  For comprehensive guidance on handling user input, see [Handling user input](handling-user-input).
</Note>

When you modify messages in the `pre:send` event, two properties control different aspects of the message:

* [`message.message.content`](#event-properties)\
  Text sent to the agent for LLM processing.

* [`message.message.message_state.input.display_text`](#event-properties)\
  Text displayed in the chat UI.

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

<ParamField path="type" type="string" required>
  Always `'pre:send'`.
</ParamField>

<ParamField path="message" type="object" required>
  The message payload to send to the agent. It contains the user's input and metadata.
</ParamField>

<ParamField path="message.message" type="object" required>
  The message object containing the content.
</ParamField>

<ParamField path="message.message.content" type="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`](#event-properties).
</ParamField>

<ParamField path="message.message.message_state" type="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.
</ParamField>

<ParamField path="message.message.message_state.input.display_text" type="string">
  Text displayed to the user in the chat UI. When present, this property takes priority over [`message.message.content`](#event-properties) 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.
</ParamField>

## Examples

The following example demonstrates how to modify message content and add metadata before sending to the agent:

```javascript theme={null}
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:

```javascript theme={null}
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:

* **[Translation](handling-user-input#use-case-1-message-translation)**: Translate messages for the agent while preserving the original language in the UI.
* **[Input sanitization](handling-user-input#use-case-2-input-sanitization)**: Remove sensitive information before sending to the agent.
* **[Content transformation](handling-user-input#use-case-3-content-transformation)**: Transform user input into standardized formats.
* **[Adding context](handling-user-input#use-case-4-adding-context)**: Enrich messages with metadata without cluttering the UI.

<Card title="Do you need practical examples?" icon="text-align-start" href="https://www.ibm.com/docs/SSAVQO/deploy/web_chat_agent/tutorials/tutorials_lp.html" arrow="true" cta="Learn with walk-throughs" horizontal>
  Learn how to apply the features available for embedded chat into your implementation with guidance and examples.
</Card>