> ## 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 when you want the persona to treat the text as a user turn and respond.

Use `addContext()` when you want to add application state or user-action context without triggering an immediate persona response.

<Note>`sendUserMessage()` 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

Use `addContext()` to provide contextual information that the LLM can use on the next user turn:

```javascript theme={"system"}
// Add context without sending a user message
anamClient.addContext("User clicked the checkout button");
```

The persona will not respond immediately. The context is available the next time the user speaks or sends a message.

<Note>
  `addContext()` requires SDK version 4.11.0 or higher and an active streaming
  session. It throws an error if the client is not streaming or there is no
  active session.
</Note>

### Triggering Specific Flows

```javascript theme={"system"}
// Add context without triggering a response
anamClient.addContext(
  "User navigated to pricing page and spent 30 seconds reading",
);

// Trigger a specific conversation flow
anamClient.sendUserMessage("I want to learn about your pricing plans");
```

### 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?");

// Add context about user actions without updating the transcript
anamClient.addContext("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>