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

# send()

Sends a message to the agent. Supports both visible messages and silent messages that are hidden from the chat UI.

## Syntax

```javascript theme={null}
await instance.send(message);
await instance.send(message, options);
```

## Parameters

<ParamField path="message" type="string | object" required>
  The message to send. The value can be a simple string or a [`MessageRequest`](#MessageRequest-structure) object.
</ParamField>

<ParamField path="options" type="object">
  Optional settings. Use `{ silent: true }` to hide the message from the UI.
</ParamField>

## Returns

<ResponseField name="Promise<void>">
  Resolves when the message is sent.
</ResponseField>

## Examples

The following example sends a simple text message:

```javascript theme={null}
// Send a visible message
await instance.send('Hello, how can you help me?');

// Send a silent message (hidden from UI)
await instance.send('User clicked help button', { silent: true });
```

## Considerations

### `silent` option

Silent messages are sent to the agent but remain hidden from the chat UI. Use the `silent` option when you need to trigger agent responses without cluttering the conversation.

When you send a silent message, the following sequence occurs:

1. Message is sent to the agent for processing.
2. Message is hidden from the chat UI.
3. Agent can respond (response is visible to user).
4. User only sees the agent's response, not the trigger.

The following example triggers a welcome message:

```javascript theme={null}
await instance.send('', { silent: true });
```

The following example sends a feedback notification:

```javascript theme={null}
async function handleFeedback(rating, comment) {
    const message = `User feedback: ${rating} stars - ${comment}`;
    await instance.send(message, { silent: true });
}
```

The following example tracks a user action:

```javascript theme={null}
await instance.send('User viewed pricing page', { silent: true });
```

**Advanced implementation with `MessageRequest` with `additional_properties`**

For more control, use a `MessageRequest` object to specify message properties including visibility, thread targeting, and custom context.

### `MessageRequest` structure

```javascript theme={null}
{
  message: {
    role: 'user',
    content: 'Your message text',
    additional_properties: {
      display_properties: {
        skip_render: boolean  // true = hidden, false = visible
      }
    }
  },
  context: {                  // Optional: custom context data
    key: 'value'
  }
}
```

The following example sends a silent message with `MessageRequest`:

```javascript theme={null}
await instance.send({
    message: {
        role: 'user',
        content: 'User clicked help button',
        additional_properties: {
            display_properties: {
                skip_render: true  // Hide from UI
            }
        }
    }
});
```

The following example sends a message with Thread and Context:

```javascript theme={null}
await instance.send({
    message: {
        role: 'user',
        content: 'I need help with my order'
    },
    context: {
        user_location: 'checkout_page',
        cart_value: 150.00
    }
});
```

### Override behavior

When you use both a `MessageRequest` object and the `{ silent: true }` option, the `{ silent: true }` option takes precedence:

```javascript theme={null}
// The { silent: true } option overrides skip_render in the message
await instance.send({
    message: {
        role: 'user',
        content: 'Message',
        additional_properties: {
            display_properties: { skip_render: false }  // Will be overridden!
        }
    }
}, { silent: true });  // Final result: message is hidden
```

**Priority rules for override behavior:**

1. `{ silent: true }` option
   It always hides the message.

2. `skip_render: true` in message\
   It hides the message.

3. `skip_render: false` in message
   It shows the message.

4. No option or property
   It shows the message. This is the default.

**When to use each approach:**

* Use `{ silent: true }` for simple cases and quick overrides.
* Use `additional_properties.display_properties.skip_render` when building `MessageRequest` objects.
* Combine both when you need to override message object settings at runtime.

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