How To
Summary
This technote provides guidance on embedding the Watsonx Orchestrate AI Assistant web chat into the IBM API Connect Developer Portal
Steps
1. Get the correct embedding snippet using the steps at Embedding the web chat on your page in watsonx Orchestrate product documentation. The direct link to the page might change in the future but the concept remains the same.
Here is an example:
Note: Do not reuse example snippets directly. Always generate your own snippet with your integration ID and service instance ID.
<script>
window.watsonAssistantChatOptions = {
integrationID: "", // The ID of this integration.
region: "aws-us-east-1", // The region your integration is hosted in.
serviceInstanceID: "", // The ID of your service instance.
orchestrateUIAgentExtensions: false, // If you wish to enable optional UI Agent extensions.
onLoad: async (instance) => { await instance.render(); }
};
setTimeout(function(){
const t=document.createElement('script');
t.src="https://web-chat.global.assistant.watson.appdomain.cloud/versions/" + (window.watsonAssistantChatOptions.clientVersion || 'latest') + /WatsonAssistantChatEntry.js";
document.head.appendChild(t);
});
</script>
2. Validate Network Access
If your environment is behind a firewall, ensure the URLs listed in the Security section at the How the web chat works page in watsonx Orchestrate product documentation are accessible from the host where the Developer Portal is deployed. For example, for API Connect OVA deployments, this means validating access from the portal VM.
If your environment is behind a firewall, ensure the URLs listed in the Security section at the How the web chat works page in watsonx Orchestrate product documentation are accessible from the host where the Developer Portal is deployed. For example, for API Connect OVA deployments, this means validating access from the portal VM.
3. Embed the Snippet in a Custom Block
Follow the detailed Tutorial: Adding a custom block to the front page in IBM API Connect product documentation to add the snippet from Step 1 into a block and display it on the homepage.
Follow the detailed Tutorial: Adding a custom block to the front page in IBM API Connect product documentation to add the snippet from Step 1 into a block and display it on the homepage.
4. Verify the chat icon is visible in the portal home page. Here is a sample screenshot :
Troubleshooting Tips
- If the script appears as plain text, ensure it was pasted in Source mode in the block editor. Here are detailed steps :
- Open the block editor where you added the chatbot script.
- Click the Source button in the toolbar (usually found at the top-left of the editor).
- Paste your script only after switching to Source mode.
- Click Source again to return to the normal view and confirm the script is no longer visible as text.
- Save the block.
- Here is a sample screenshot
- If the widget does not load:
- Check browser developer tools for errors.
- Confirm network access to required Watsonx URLs.
- If you're using API Connect version 10.0.5.7, upgrade to 10.0.5.8 or later to avoid CKEditor sanitization issues.
Document Location
Worldwide
[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSMNED","label":"IBM API Connect"},"ARM Category":[{"code":"a8mKe000000CaZYIA0","label":"API Connect-\u003EAPIC Portal"}],"ARM Case Number":"TS019781696","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"and future releases;10.0.5"}]
Was this topic helpful?
Document Information
Modified date:
30 September 2025
UID
ibm17246668