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