Context variables allow your web application to pass additional information to the embedded web chat and make that information available to the agent runtime for use during message processing. This feature enables more personalized and context-aware interactions by providing the agent with relevant data about the user or the environment.
spec_version: v1style: reactname: askHR_agentllm: watsonx/meta-llama/llama-3-2-90b-vision-instructdescription: You are a helpful agent that answers HR-related queriesinstructions: >- You have access to the following context values: `clientID: {clientID}` `name: {name}` `role: {role}` `user_name: {user_name}` `email_id: {email_id}` Pass these values exactly as provided. Do not ask the user for these values — they are always available in the context.collaborators: []tools: []context_access_enabled: truecontext_variables: - clientID - name - role - user_name - email_id
Key points:
List all context variables in the context_variables array
Reference them in instructions by using {variable_name} syntax
Instruct the agent not to ask users for these values since they’re provided automatically
The agent can use these values when it calls tools or responds to users
Important naming conventions:
Do NOT use the wxo_ prefix in your custom context variable names. This prefix is reserved for system variables.
If the same context variable name exists in both the JWT and the instance method (pre:send), the JWT value takes precedence over the /runs API value.
To avoid conflicts, use different variable names for JWT context and dynamic context that is passed through instance methods.
This method embeds context variables directly in the JWT token. It is suitable for stable, identity-related context that doesn’t change frequently, such as user ID, role, or organization ID.
Fixed user identity information (user ID, role, department)
Organization or tenant identifiers
Permissions or access levels
Any context that remains constant throughout the session
You can add context variables to a JWT token by using a JavaScript script. The following script shows how to include context variables inside a JWT token in your server:
createJWT
/** * JWT Creation Service for watsonx Orchestrate Secure Embed Chat * * This module handles the server-side creation of JSON Web Tokens (JWTs) for secure * authentication with IBM watsonx Orchestrate embed chat. It demonstrates: * * 1. RS256 JWT signing using your private key * 2. Optional user payload encryption using IBM's public key * 3. Cookie-based anonymous user tracking * 4. Session-based user information enrichment * * Security Notes: * - Never expose your private key to the client side * - Always generate JWTs server-side only * - Use HTTPS in production environments * - Adjust token expiration times based on your security requirements */const fs = require("fs");const path = require("path");const express = require("express");const { v4: uuid } = require("uuid");const jwtLib = require("jsonwebtoken");const NodeRSA = require("node-rsa");const router = express.Router();/** * Load your server-side RSA private key (PEM format) * * This key is used to sign JWTs with the RS256 algorithm. The corresponding public key * must be uploaded to your watsonx Orchestrate instance security settings. * * IMPORTANT: Keep this file secure and never expose it to clients! * * Generate a new key pair using either method: * * Method 1 - Using ssh-keygen: * ssh-keygen -t rsa -b 4096 -m PEM -f example-jwtRS256.key * openssl rsa -in example-jwtRS256.key -pubout -outform PEM -out example-jwtRS256.key.pub * * Method 2 - Using openssl directly: * openssl genrsa -out example-jwtRS256.key 4096 * openssl rsa -in example-jwtRS256.key -pubout -out example-jwtRS256.key.pub */const PRIVATE_KEY_PATH = path.join(__dirname, "../keys/example-jwtRS256.key");if (!fs.existsSync(PRIVATE_KEY_PATH)) { throw new Error(`Private key not found at ${PRIVATE_KEY_PATH}`);}const PRIVATE_KEY = fs.readFileSync(PRIVATE_KEY_PATH);/** * Load IBM's RSA public key (PEM format) * * This key is provided by IBM watsonx Orchestrate and is used to encrypt the user_payload * field in the JWT. This ensures that sensitive user information cannot be read by clients, * as only IBM's servers can decrypt it. * * You can obtain this key by: * 1. Running the wxo-embed-security-v4.sh script (recommended) * 2. Calling the generate-key-pair API endpoint manually * * The encrypted payload will be decrypted server-side by watsonx Orchestrate. */const IBM_PUBLIC_KEY_PATH = path.join(__dirname, "../keys/ibmPublic.key.pub");if (!fs.existsSync(IBM_PUBLIC_KEY_PATH)) { throw new Error(`IBM public key not found at ${IBM_PUBLIC_KEY_PATH}`);}const IBM_PUBLIC_KEY = fs.readFileSync(IBM_PUBLIC_KEY_PATH);/** * Cookie lifetime configuration * * This defines how long the anonymous user ID cookie will persist. * Currently set to 60ms for demonstration purposes. For production, use a longer duration * such as 45 days (45 * 24 * 60 * 60 * 1000 milliseconds). */const TIME_15_MINUTES = 15 * 60 * 1000; // 15 minutes for demonstration. Adjust based on your security requirements./** * Create a signed JWT string for the Orchestrate embedded chat client. * * This function constructs a JWT with the following structure: * * @param {string} anonymousUserID - A stable identifier for anonymous users (from cookie) * @param {object|null} sessionInfo - Optional authenticated user session data * * JWT Claims: * - sub: Subject (user identifier) - should be a stable, unique ID for the user * - user_payload: Encrypted user data that will be decrypted by watsonx Orchestrate * - name: User's display name * - custom_message: Any custom message or metadata * - custom_user_id: Your application's internal user ID * - sso_token: Single sign-on token if applicable * - context: Additional context data accessible by the agent * - clientID: Your client/organization identifier * - user_name: User's name for display in chat * - user_role: User's role (e.g., Admin, User, Guest) * * @returns {string} A signed JWT token string */function createJWTString(anonymousUserID, sessionInfo) { // Base JWT claims structure // Customize these fields based on your application's requirements const jwtContent = { // Subject: Unique identifier for the user // In production, use a real user ID from your authentication system sub: "FHY1234DD5", // Example value. Replace with actual user ID. // User payload: It will be encrypted with IBM's public key // This data is sensitive and will only be readable by watsonx Orchestrate servers // Optional user_payload: { sso_token: "sso_token", }, // Context: Additional metadata accessible by the agent // This data is NOT encrypted and can be read by the client context: { clientID: "865511", // Your client/organization ID user_name: "Ava", // Display name in chat user_role: "Admin", // User role }, }; // Enrich the JWT with authenticated session data if available // In production, this would come from your authentication system if (sessionInfo) { jwtContent.user_payload.name = sessionInfo.userName; jwtContent.user_payload.custom_user_id = sessionInfo.customUserID; } // Encrypt the user_payload using IBM's RSA public key // This ensures sensitive user data cannot be read by clients // Only watsonx Orchestrate servers can decrypt this data if (jwtContent.user_payload) { const rsaKey = new NodeRSA(IBM_PUBLIC_KEY); const dataString = JSON.stringify(jwtContent.user_payload); const utf8Data = Buffer.from(dataString, "utf-8"); // Encrypt and encode as base64 string jwtContent.user_payload = rsaKey.encrypt(utf8Data, "base64"); } // Sign the JWT using RS256 algorithm with your private key // The token expiration should be set based on your security requirements // Common values: "1h" (1 hour), "6h" (6 hours), "1d" (1 day) const jwtString = jwtLib.sign(jwtContent, PRIVATE_KEY, { algorithm: "RS256", expiresIn: "15m", // 15 minutes for demonstration. Adjust based on your security requirements. }); return jwtString;}/** * Retrieve or create a stable anonymous user ID stored in a cookie * * This function ensures that anonymous users maintain a consistent identity across * page refreshes and sessions. The ID is stored in a secure HTTP-only cookie. * * Benefits: * - Prevents user identity from changing mid-session * - Enables conversation continuity for anonymous users * - Provides basic user tracking without requiring authentication * * @param {object} request - Express request object * @param {object} response - Express response object * @returns {string} The anonymous user ID */function getOrSetAnonymousID(request, response) { // Check if an anonymous ID already exists in cookies let anonymousID = request.cookies["ANONYMOUS-USER-ID"]; // Generate a new ID if none exists if (!anonymousID) { // Create a short, readable ID using UUID (first 5 characters for demonstration) // In production, you might want to use the full UUID for better uniqueness anonymousID = `anon-${uuid().slice(0, 5)}`; } // Set or refresh the cookie with each request to maintain the session response.cookie("ANONYMOUS-USER-ID", anonymousID, { expires: new Date(Date.now() + TIME_45_DAYS), httpOnly: true, // Prevents client-side JavaScript from accessing the cookie (security) sameSite: "Lax", // Provides CSRF protection while allowing normal navigation secure: false, // Set to true in production when using HTTPS }); return anonymousID;}/** * Parse authenticated session information from cookies * * This function retrieves user session data if the user is authenticated. * In a production application, you would: * 1. Verify the session token/cookie * 2. Fetch user information from your database or identity provider * 3. Validate user permissions * * For this demonstration, we simply parse a JSON string from a cookie. * * @param {object} request - Express request object * @returns {object|null} Session info object or null if not authenticated */function getSessionInfo(request) { const sessionInfo = request.cookies?.SESSION_INFO; if (!sessionInfo) return null; try { // Parse the JSON session data return JSON.parse(sessionInfo); } catch { // Return null if parsing fails (invalid JSON) return null; }}/** * Express route handler for JWT creation * * This endpoint is called by the client to obtain a fresh JWT token. * The token is required for secure authentication with watsonx Orchestrate embedded chat. * * Flow: * 1. Retrieve or create an anonymous user ID (stored in cookie) * 2. Check for authenticated session information * 3. Generate a signed JWT with user data * 4. Return the JWT as plain text response * * The client will include this JWT in the wxOConfiguration.token field * when initializing the embedded chat. * * @param {object} request - Express request object * @param {object} response - Express response object */function createJWT(request, response) { // Ensure we have a stable user ID (anonymous or authenticated) const anonymousUserID = getOrSetAnonymousID(request, response); // Get authenticated session data if available const sessionInfo = getSessionInfo(request); // Create and sign the JWT const token = createJWTString(anonymousUserID, sessionInfo); // Return the JWT as plain text response.send(token);}// Define the GET endpoint that returns a signed JWT string// This endpoint is called by the client before initializing the chatrouter.get("/", createJWT);module.exports = router;
After the JWT token generates, pass it to the embedded web chat:You can check the examples for watsonx Assistant web chat that are mostly compatible with the watsonx Orchestrate embedded chat to see how to use this code exampleAfter the JWT token generates, pass it to the embedded web chat. The following example shows how to do that:
JavaScript
<script> function getUserId() { let embed_user_id = getCookie('embed_user_id'); if (!embed_user_id) { embed_user_id = Math.trunc(Math.random() * 1000000); setCookie('embed_user_id', embed_user_id); } return embed_user_id; } function getCookie(name) { console.log('getCookie'); const value = `; ${document.cookie}`; const parts = value.split(`; ${name}=`); if (parts.length === 2) return parts.pop().split(';').shift(); } function setCookie(name, value) { document.cookie = `${name}=${value}; path=/`; } function onChatLoad(instance) { // Save instance for later use window.wxoChatInstance = instance; console.log('Chat loaded with JWT authentication'); } async function getIdentityToken() { // This will make a call to your server to request a new JWT. const result = await fetch( "http://localhost:3000/createJWT?user_id=" + getUserId() ); window.wxOConfiguration.token = await result.text(); } window.wxOConfiguration = { orchestrationID: "your-orchestration-id", hostURL: "https://us-south.watson-orchestrate.cloud.ibm.com", rootElementID: "root", deploymentPlatform: "ibmcloud", crn: "your-crn", chatOptions: { agentId: "your-agent-id", agentEnvironmentId: "your-agent-environment-id", onLoad: onChatLoad }, }; getIdentityToken().then(() => { const script = document.createElement("script"); script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`; script.addEventListener("load", function () { wxoLoader.init(); }); document.head.appendChild(script); });</script>
This method dynamically injects context variables into each message by using the pre:send event handler. It’s ideal for dynamic context that changes frequently or varies per message, such as current page, selected profile, or user input.
The following example shows the simplest way to inject context variables into messages:
<html><body> <div id="root"></div> <script> // Handler to inject context into outgoing messages function preSendHandler(event, instance) { event.message.context = { ...event.message.context, clientID: "12345", user_name: "John Doe", user_role: "Employee" }; console.log('Context injected:', event.message.context); } // Called when chat loads function onChatLoad(instance) { // Register the pre:send event handler instance.on('pre:send', preSendHandler); } // Configure the chat window.wxOConfiguration = { orchestrationID: "your-orchestration-id", hostURL: "https://us-south.watson-orchestrate.cloud.ibm.com", rootElementID: "root", deploymentPlatform: "ibmcloud", crn: "your-crn", chatOptions: { agentId: "your-agent-id", onLoad: onChatLoad } }; // Load the chat script const script = document.createElement('script'); script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`; script.addEventListener('load', function () { wxoLoader.init(); }); document.head.appendChild(script); </script></body></html>
Event choice: Use pre:send instead of send for context injection. The pre:send event fires before the message is sent, helping ensure that context is included in the request. The send event fires after the message is already sent.
