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.
sendUserMessage() requires SDK version 3.3.0 or higher
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 addContext() to provide contextual information that the LLM can use on the next user turn:
// Add context without sending a user messageanamClient.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.
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.
// Add context without triggering a responseanamClient.addContext( "User navigated to pricing page and spent 30 seconds reading",);// Trigger a specific conversation flowanamClient.sendUserMessage("I want to learn about your pricing plans");
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 serviceasync 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.
Here’s a complete example showing how to use sendUserMessage() with proper transcript management:
import { createClient } from "@anam-ai/js-sdk";// Initialize the clientconst anamClient = createClient(sessionToken);await anamClient.streamToVideoElement("video-element-id");// Function to update your UI transcriptfunction 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 transcriptfunction 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 usagesendMessage("What products do you recommend?");// Add context about user actions without updating the transcriptanamClient.addContext("User added item to cart with ID product_123");
The sendUserMessage() method throws errors in two scenarios:
// Error: Not currently streamingtry { anamClient.sendUserMessage("Hello");} catch (error) { // "Failed to send user message: not currently streaming"}// Error: No active sessiontry { 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");}
