Skip to main content

​
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.
Requires SDK version 3.3.0 or higher

​
Basic Usage

Send a message as if the user typed or spoke it: 
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
anamClient.sendUserMessage("Hi there!");

​
Providing Context to the LLM

Provide contextual information about user actions that the LLM can respond to: 
// 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."
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
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: 
// 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");
}
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.

​
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
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: 
// 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: 
if (anamClient.isStreaming()) {
  anamClient.sendUserMessage("Hello");
}

​
Next Steps

Events

Learn how to handle message events and build interactive experiences

Interrupt Command

Stop the persona from speaking mid-response