​
Overview

The sendUserMessage() method allows you to programmatically send text messages on behalf of the user. This is useful for sending contextual information or triggering specific persona responses without actual user input.
Requires SDK version 3.3.0 or higher

​
Basic Usage

Send a message as if the user typed or spoke it: 
await 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

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

// Simulate a user greeting when the session starts
await anamClient.sendUserMessage("Hi there!");

​
Providing Context to the LLM

A powerful use case is providing contextual information about user actions that the LLM can respond to: 
// Inform the AI about user actions
await 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."
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.

​
Triggering Specific Flows

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

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

​
Custom Client-Side Transcription

The sendUserMessage() method enables you to implement your own client-side speech-to-text transcription. You can capture and transcribe audio using your preferred service, then send the transcribed messages directly: 
// 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
  await anamClient.sendUserMessage(transcribedText);

  // Update your UI transcript
  addMessageToTranscript(transcribedText, "user");
}
This approach gives you full control over the transcription process, allowing you to use specialized transcription models, handle multiple languages, or implement custom preprocessing of the audio before sending it to the persona.

​
Complete Example

Here’s a complete example showing how to use sendUserMessage() with proper transcript management: 
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
async function sendUserMessage(message) {
  // Add to transcript manually since sendUserMessage doesn't trigger events
  addMessageToTranscript(message, "user");

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

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

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

​
Future Improvements

In future SDK versions, we plan to introduce a dedicated sendSystemMessage() method that will be better suited for sending contextual information and system-level messages to the LLM. This will provide clearer separation between user messages and system context.

​
Next Steps

Events

Learn how to handle message events and build interactive experiences

Talk Commands

Control persona responses programmatically