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.

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

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

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

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.

Triggering Specific Flows

// 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:

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

// 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:

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