Add watsonx Orchestrate Embed Chat Examples with Node.js Implementations #27
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # Byte-compiled Python files | ||
| *.py[cod] | ||
| __pycache__/ | ||
|
|
||
| # C extensions | ||
| *.so | ||
|
|
||
| # Distribution / packaging | ||
| .Python | ||
| build/ | ||
| develop-eggs/ | ||
| dist/ | ||
| downloads/ | ||
| eggs/ | ||
| .eggs/ | ||
| lib/ | ||
| lib64/ | ||
| parts/ | ||
| sdist/ | ||
| var/ | ||
| *.egg-info/ | ||
| .installed.cfg | ||
| *.egg | ||
|
|
||
| # Virtual environments | ||
| venv/ | ||
| ENV/ | ||
| env/ | ||
| .venv/ | ||
| .env/ | ||
|
|
||
| # Setuptools | ||
| *.lock | ||
| *.log | ||
| pip-log.txt | ||
| pip-delete-this-directory.txt | ||
|
|
||
| # Unit test / coverage reports | ||
| htmlcov/ | ||
| .tox/ | ||
| .nox/ | ||
| .coverage | ||
| *.cover | ||
| coverage.* | ||
| .cache | ||
| .pytest_cache/ | ||
|
|
||
| # Jupyter Notebook | ||
| .ipynb_checkpoints | ||
|
|
||
| # pyenv | ||
| .python-version | ||
|
|
||
| # Editor / IDE-specific files | ||
| .vscode/ | ||
| .idea/ | ||
| *.swp | ||
| *~ | ||
| *.sublime-workspace | ||
|
|
||
| # Build scripts | ||
| .DS_Store | ||
| *.bak | ||
| *.tmp | ||
|
|
||
| # Ignore local environment and configuration files | ||
| .env | ||
| .env.* | ||
| .idea/ | ||
| .vscode/ | ||
| coverage/ | ||
|
|
||
| # Ignore local examples | ||
| chat_examples/embed_chat/secure-embed-chat/node_modules | ||
| chat_examples/embed_chat/anonymous-embed-chat/node_modules | ||
| *node_modules |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| # IBM watsonx Orchestrate Embed Chat Examples | ||
|
|
||
| This directory contains example implementations for integrating IBM watsonx Orchestrate embed chat into your applications. | ||
|
|
||
| ## Available Examples | ||
|
|
||
| ### 1. [Anonymous Embed Chat (Node.js)](./anonymous-embed-chat-node) | ||
|
|
||
| A simple, anonymous embed chat integration **without security enabled**. | ||
|
|
||
| **Use this when:** | ||
| - You're in development/testing phase | ||
| - Your chatbot is public-facing and doesn't require user authentication | ||
| - You're building a proof-of-concept | ||
| - No sensitive data or systems are accessed | ||
|
|
||
| **Quick start:** | ||
|
There was a problem hiding this comment. Don't repeat this info here. If you want a table of contents, fine but leave the instructions in each file. |
||
| ```bash | ||
| cd anonymous-embed-chat-node | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ### 2. [Secure Embed Chat (Node.js)](./secure-embed-chat-node) | ||
|
|
||
| A secure embed chat implementation with JWT-based authentication and encryption. | ||
|
|
||
| **Use this when:** | ||
| - You need user authentication in production environments | ||
| - You want to pass user context securely to the chat | ||
| - You need to encrypt sensitive user data | ||
| - You're implementing SSO integration (On-Behalf-Of flow) | ||
| - Your instance accesses sensitive data or protected systems | ||
|
|
||
| **Quick start:** | ||
| ```bash | ||
| cd secure-embed-chat-node | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Getting Started with Embedded Chat](https://developer.watson-orchestrate.ibm.com/webchat/get_started) | ||
| - [Context Variables](https://developer.watson-orchestrate.ibm.com/webchat/context_variables) | ||
| - [Security Architecture](https://developer.watson-orchestrate.ibm.com/agents/integrate_agents#security-architecture) | ||
| - [IBM Docs: Securing Embedded Chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=applications-securing-embedded-chat) | ||
| - [Configuring security for embedded chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-embedded) | ||
| - [Configuring security with scripting](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-scripting) | ||
|
|
||
| ## Quick Comparison | ||
|
There was a problem hiding this comment. Definitely don't repeat this here. |
||
|
|
||
| | Feature | Anonymous | Secure | | ||
| |---------|-----------|--------| | ||
| | User Authentication | ❌ No | ✅ Yes | | ||
| | JWT Required | ❌ No | ✅ Yes | | ||
| | Production Ready | ⚠️ Public only | ✅ Yes | | ||
| | Sensitive Data | ❌ Not recommended | ✅ Yes | | ||
|
|
||
| ## Requirements | ||
|
|
||
| All examples require: | ||
| - Node.js version 16.15.1 or higher | ||
| - npm (Node Package Manager) | ||
| - OpenSSL (for key generation in secure mode) | ||
|
|
||
| ## Support | ||
|
|
||
| For issues, questions, or contributions, please refer to the main project documentation or contact IBM watsonx Orchestrate support. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,171 @@ | ||
| # Anonymous Embed Chat for IBM watsonx Orchestrate (Sample) | ||
|
|
||
| **For complete documentation, please visit:** | ||
| - [Getting Started with Embedded Chat](https://developer.watson-orchestrate.ibm.com/webchat/get_started) | ||
| - [Context Variables](https://developer.watson-orchestrate.ibm.com/webchat/context_variables) | ||
| - [IBM Docs: Securing Embedded Chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=applications-securing-embedded-chat) | ||
| - [Configuring security for embedded chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-embedded) | ||
| - [Configuring security with scripting](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-scripting) | ||
|
|
||
| ## Overview | ||
|
|
||
| This example demonstrates a simple, anonymous embed chat integration **without security enabled**. When security is disabled, anonymous authentication is enabled for a limited set of APIs required for the chat to work for anonymous users. | ||
|
|
||
| ### ⚠️ Critical Security Warning | ||
|
|
||
| **Use this mode ONLY when:** | ||
| - You're in development/testing phase | ||
| - Your chatbot is public-facing and doesn't require user authentication | ||
| - You're building a proof-of-concept | ||
| - **Your instance does NOT show or provide access to sensitive data** | ||
| - **Your instance does NOT have tools configured with functional credentials that access sensitive data in protected systems** | ||
|
|
||
| ### 🔒 When to Use Secure Mode Instead | ||
|
|
||
| **You MUST use [secure-embed-chat-node](../secure-embed-chat-node) if:** | ||
| - You're deploying to production with authenticated users | ||
| - Your instance accesses sensitive data or protected systems | ||
| - You need user-specific context or audit trails | ||
| - You're implementing SSO or On-Behalf-Of (OBO) flow | ||
| - Your application requires compliance with security standards | ||
|
|
||
| **Before disabling security, you must:** | ||
| 1. Review ALL integrations in your instance | ||
| 2. Ensure no sensitive data is exposed | ||
| 3. Verify no tools have credentials accessing protected systems | ||
| 4. Document the security decision and rationale | ||
|
|
||
| ## What This Example Demonstrates | ||
|
|
||
| - Basic wxO embed chat integration without JWT authentication | ||
| - Simple HTML page with embedded chat | ||
| - Anonymous user access (no authentication required) | ||
| - Limited API access (only anonymous-enabled endpoints) | ||
|
|
||
| ## Security Implications | ||
|
|
||
| ### What You Lose Without Security | ||
|
|
||
| When security is disabled, you lose: | ||
| - **User authentication** - No way to verify user identity | ||
| - **Access control** - Cannot restrict access based on user permissions | ||
|
There was a problem hiding this comment. I think this is a bit too vague. You should be clear here that this does not give anyone access to their tenant. This doesn't allow random users to log into the platform UI or do anything to their instance. This only thing this is allows is for customers to use their wxo chat and all of its capabilities and any apis it has access to it. It does not grant full access to wxo. Also, I'm not sure how much of this you should write here in this example. All of this information should be in the product documentation and you should avoid just duplicating that documentation. This is important enough of a topic to repeat some of it but I would try to limit the duplication. |
||
| - **Encrypted payloads** - Sensitive data cannot be securely transmitted | ||
| - **Audit trails** - Limited ability to track user actions | ||
| - **SSO integration** - Cannot use On-Behalf-Of (OBO) flow | ||
| - **User context** - Cannot pass authenticated user information | ||
|
|
||
| ### Risks of Anonymous Mode | ||
|
|
||
| - **Data exposure** - Any data accessible to the agent is accessible to anyone | ||
| - **Unauthorized access** - No way to prevent access to the chat | ||
| - **No accountability** - Cannot track who performed what actions | ||
| - **Limited functionality** - Some features require authenticated users | ||
| - **Compliance issues** - May not meet regulatory requirements | ||
|
|
||
| ## Running the Code | ||
|
|
||
| This example requires having NodeJS installed (version 16.15.1 or higher). | ||
|
There was a problem hiding this comment. No, it doesn't. The example should work right from the file system. Or if you're a developer and have the preview extension in vscode, that would work too. I don't think this is necessary, but if you really want to include something here anyway, I would separate this out into a separate document that can be shared by all the example so you're not just repeating all of this in every example. And that shared document can have a section that's more like, if you want to launch an html file from a web server, there are a number of ways to do that. If you are using VSCode, there is a "Live Preview" extension from Microsoft that will launch a server for you. I think there's an npm package you might just be able to launch with |
||
|
|
||
| ### Running the Server | ||
|
|
||
| The server serves the static HTML file from `http://localhost:5555`. | ||
|
|
||
| 1. Navigate to the anonymous-embed-chat-node directory: | ||
| ```bash | ||
| cd embed_chat_examples/anonymous-embed-chat-node | ||
| ``` | ||
| 2. Install dependencies: | ||
| ```bash | ||
| npm install | ||
| ``` | ||
| 3. Start the server: | ||
| ```bash | ||
| npm start | ||
| ``` | ||
| 4. The server will be available at `http://localhost:5555`. | ||
|
|
||
| ### Viewing the Example | ||
|
|
||
| - After starting the server, open [http://localhost:5555/](http://localhost:5555/) in your browser. | ||
| - The wxO embed chat will load without requiring authentication. | ||
|
|
||
| ## Setting up your own agent | ||
|
|
||
| This example is configured to use placeholder values. To use your own agent: | ||
|
|
||
| 1. **Configure your agent**: | ||
|
There was a problem hiding this comment. I would probably also move this to a common place (or just rely on the product documentation) because this info is going to be exactly the same for every example. We shouldn't have to duplicate this every time. |
||
| - Open [`static/index.html`](static/index.html) | ||
| - Replace the entire `wxOConfiguration` object with the configuration from your embed script | ||
| - You can find the embed script in your agent's settings in the watsonx Orchestrate console | ||
| - The `wxOConfiguration` should include: | ||
| - `orchestrationID` - Your orchestration ID from the embed code | ||
| - `hostURL` - Your watsonx Orchestrate instance URL | ||
| - `agentId` - Your agent's unique identifier | ||
| - `agentEnvironmentId` - Your agent's environment identifier (optional) | ||
|
|
||
| **Note about `agentEnvironmentId`:** | ||
|
|
||
| - This field is **optional** and **not required** for draft environments | ||
| - Only include `agentEnvironmentId` when connecting to a **live environment** | ||
| - For draft environments, you can omit this field from the configuration | ||
|
|
||
| 2. **Disable security in watsonx Orchestrate** (if enabled): | ||
| - Open the Security settings for your wxO embed chat in the watsonx Orchestrate console | ||
| - Ensure security is disabled for anonymous access | ||
| - For detailed instructions, see: | ||
| - [IBM Docs: Securing Embedded Chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=applications-securing-embedded-chat) | ||
| - [Configuring security for embedded chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-embedded) | ||
| - [Configuring security with scripting](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-scripting) | ||
|
|
||
| ## Key Files | ||
|
|
||
| - [`server.js`](server.js) - Simple Express server for serving static files | ||
| - [`static/index.html`](static/index.html) - wxO embed chat integration without authentication | ||
|
|
||
| ## When to Use This Example | ||
|
|
||
| Use this anonymous embed chat example **ONLY** when: | ||
| - You're in development/testing phase | ||
| - Your chatbot is public-facing and doesn't require user authentication | ||
| - You're building a proof-of-concept or demo | ||
| - **No sensitive data or systems are accessed** | ||
| - **No compliance requirements exist** | ||
|
|
||
| ## When to Use Secure Embed Chat | ||
|
There was a problem hiding this comment. Now you're just repeating yourself. |
||
|
|
||
| Switch to the [secure-embed-chat-node](../secure-embed-chat-node) example when: | ||
| - You need to authenticate users | ||
| - You're deploying to production with authenticated users | ||
| - You need to pass user-specific context or data | ||
| - You require audit trails of user interactions | ||
| - Your instance accesses sensitive data or protected systems | ||
| - You need SSO integration or On-Behalf-Of (OBO) flow | ||
| - Compliance or regulatory requirements apply | ||
|
|
||
| ## Comparison: Anonymous vs Secure | ||
|
There was a problem hiding this comment. This really belongs in the product documentation, not here. |
||
|
|
||
| | Feature | Anonymous (This Example) | Secure | | ||
| |---------|-------------------------|--------| | ||
| | User Authentication | ❌ No | ✅ Yes | | ||
| | JWT Required | ❌ No | ✅ Yes | | ||
| | Encrypted Payloads | ❌ No | ✅ Yes | | ||
| | User Context | ❌ None | ✅ Full | | ||
| | Audit Trails | ❌ Limited | ✅ Complete | | ||
| | SSO Integration | ❌ No | ✅ Yes | | ||
| | Production Ready | ⚠️ Public only | ✅ Yes | | ||
| | Sensitive Data | ❌ Not recommended | ✅ Yes | | ||
|
|
||
| For production deployments with authentication, see the [secure-embed-chat-node](../secure-embed-chat-node) example which demonstrates: | ||
| - JWT-based authentication with RS256 signing | ||
| - User payload encryption using IBM's public key | ||
| - Context variable passing with user identity | ||
| - Secure cookie handling and token lifecycle management | ||
| - Key management and rotation procedures | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [Getting Started Guide](https://developer.watson-orchestrate.ibm.com/webchat/get_started) | ||
| - [Security Architecture](https://developer.watson-orchestrate.ibm.com/agents/integrate_agents#security-architecture) | ||
| - [IBM Docs: Securing Embedded Chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=applications-securing-embedded-chat) | ||
| - [Configuring security for embedded chat](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-embedded) | ||
| - [Configuring security with scripting](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-configuring-security-scripting) | ||
| - [Agent Integration Documentation](https://developer.watson-orchestrate.ibm.com/agents/integrate_agents) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you should probably split this folder. I would make this
embed_chat/examples. Then you could potentially haveembed_chat/utilitiesorembed_chat/commonwhere you can put stuff to share across examples to avoid repeating things.