> ## Documentation Index
> Fetch the complete documentation index at: https://anam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# User Messages

> Send messages on behalf of the user programmatically

## Overview

The `sendUserMessage()` method sends text messages on behalf of the user programmatically. Use it to send contextual information or trigger specific persona responses without actual user input.

<Note>Requires SDK version 3.3.0 or higher</Note>

## Basic Usage

Send a message as if the user typed or spoke it:

```javascript theme={"system"}
anamClient.sendUserMessage("Hello, how can you help me today?");
```

The persona will receive this message and respond as if the user had actually said it.

## Important Considerations

<Warning>
  Messages sent via `sendUserMessage()` are not automatically added to the
  transcript. To maintain an accurate conversation history, you must manually
  add these messages to your transcript display.
</Warning>

The `sendUserMessage()` method differs from regular user messages in that:

* It does not trigger message events that would normally update your UI
* The message is sent directly to the persona without going through the normal message pipeline
* You need to handle transcript updates separately in your application

## Use Cases

### Simulating User Input

```javascript theme={"system"}
// Simulate a user greeting when the session starts
anamClient.sendUserMessage("Hi there!");
```

### Providing Context to the LLM

Provide contextual information about user actions that the LLM can respond to:

```javascript theme={"system"}
// Inform the AI about user actions
anamClient.sendUserMessage(
  "Note to AI: I just clicked the checkout button"
);

// The persona might respond with something like:
// "Thanks for shopping with us today! Let me help you complete your purchase."
```

<Tip>
  When providing context to the LLM, prefix your messages with "Note to AI:" or
  similar to make the intent clear. This helps the LLM understand that it's
  receiving contextual information rather than a direct user question.
</Tip>

### Triggering Specific Flows

```javascript theme={"system"}
// Trigger a specific conversation flow
anamClient.sendUserMessage("I want to learn about your pricing plans");

// Or provide more detailed context
anamClient.sendUserMessage(
  "Note to AI: User navigated to pricing page and spent 30 seconds reading"
);
```

### Custom Client-Side Transcription

Use `sendUserMessage()` to implement your own client-side speech-to-text transcription. Capture and transcribe audio using your preferred service, then send the transcribed messages directly:

```javascript theme={"system"}
// Example using a custom transcription service
async function handleCustomTranscription(audioStream) {
  // Use your preferred transcription service (e.g., Web Speech API, Whisper, etc.)
  const transcribedText =
    await customTranscriptionService.transcribe(audioStream);

  // Send the transcribed message to the persona
  anamClient.sendUserMessage(transcribedText);

  // Update your UI transcript
  addMessageToTranscript(transcribedText, "user");
}
```

<Note>
  With this approach you can use specialized transcription models, handle multiple
  languages, or implement custom preprocessing of the audio before sending it to the persona.
</Note>

## Complete Example

Here's a complete example showing how to use `sendUserMessage()` with proper transcript management:

```javascript theme={"system"}
import { createClient } from "@anam-ai/js-sdk";

// Initialize the client
const anamClient = createClient(sessionToken);
await anamClient.streamToVideoElement("video-element-id");

// Function to update your UI transcript
function addMessageToTranscript(message, sender) {
  const transcript = document.getElementById("transcript");
  const messageElement = document.createElement("div");
  messageElement.className = sender === "user" ? "user-message" : "ai-message";
  messageElement.textContent = message;
  transcript.appendChild(messageElement);
}

// Send a message and update the transcript
function sendMessage(message) {
  // Add to transcript manually since sendUserMessage doesn't trigger events
  addMessageToTranscript(message, "user");

  // Send the message to the persona
  anamClient.sendUserMessage(message);
}

// Example usage
sendMessage("What products do you recommend?");

// Provide context about user actions
sendMessage(
  "Note to AI: User added item to cart with ID product_123"
);
```

## Error Handling

The `sendUserMessage()` method throws errors in two scenarios:

```javascript theme={"system"}
// Error: Not currently streaming
try {
  anamClient.sendUserMessage("Hello");
} catch (error) {
  // "Failed to send user message: not currently streaming"
}

// Error: No active session
try {
  anamClient.sendUserMessage("Hello");
} catch (error) {
  // "Failed to send user message: no active session"
}
```

Always ensure the client is streaming before calling this method:

```javascript theme={"system"}
if (anamClient.isStreaming()) {
  anamClient.sendUserMessage("Hello");
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Events" icon="webhook" href="/javascript-sdk/reference/events">
    Learn how to handle message events and build interactive experiences
  </Card>

  <Card title="Interrupt Command" icon="hand" href="/javascript-sdk/reference/interrupt-command">
    Stop the persona from speaking mid-response
  </Card>
</CardGroup>