A channel is an entry point into your agent, such as a website where you would like to embed your agent, a Slack app, and so on.

​
watsonx Orchestrate channels webchat

​
Embedding webchat

To simplify integration with your website, the CLI includes the orchestrate channels webchat embed command. This command takes the name of an agent and produces a script tag that you can place in the <head></head> section of your page for the currently active environment.

[BASH]
orchestrate channels webchat embed --agent-name=test_agent1

When targeting the local environment, the command uses your agent’s draft variant. On a production instance, it defaults to using your agent’s live (deployed) variant. Below is an example of the command’s output:

[OUTPUT]
<script>
    window.wxOConfiguration = {{
        orchestrationID: "my-tenant-id",
        hostURL: "my-host-url",
        rootElementID: "root",
        showLauncher: true,
        chatOptions: {{
            agentId: "test_agent1",
            agentEnvironmentId: "my-agent-draft-env-id"
        }},
    }};
    setTimeout(function () {{
        const script = document.createElement('script');
        script.src = `my-host-url/wxochat/wxoLoader.js?embed=true`;
        script.addEventListener('load', function () {{
        wxoLoader.init();
        }});
        document.head.appendChild(script);
    }}, 0);
</script>

​
Layout configuration

The watsonx Orchestrate embed supports a flexible layout object to control how and where the chat UI appears.

ParameterTypeDefaultDescription
rootElementIDstring—(fullscreen-overlay only) ID of the container node to mount chat into.
showLauncherbooleantrue(fullscreen-overlay only) Show the bubble launcher (true) orrender chat immediately (false).
layout.formstring’float’Container mode (‘fullscreen-overlay’, ‘float’, ‘custom’).
layout.widthstring—(float only) Popup width (e.g. ‘350px’, ‘30rem’).
layout.heightstring—(float only) Popup height (e.g. ‘500px’, ‘40rem’).
layout.showOrchestrateHeaderbooleantrueRender the standard header bar (true) or hide it(false).
layout.customElementHTMLElement—element reference to render into.
<script>
window.wxOConfiguration = {
  orchestrationID: "my-tenant-id",
  hostURL: "my-host-url",
  rootElementID: "root",            // fullscreen-overlay only
  showLauncher: false,              // fullscreen-overlay only, false = direct render, true = launcher bubble

  chatOptions: {
    agentId: "12345_test_agent1",            // required
    agentEnvironmentId: "my-agent-env-id"    // required
  },

  layout: {
    form: 'float',                           // 'fullscreen-overlay' | 'float' | 'custom'
    width: '600px',                          // float only
    height: '600px',                         // float only
    showOrchestrateHeader: true,            // hide header if false
    customElement: hostElement              // custom only
  }
};

setTimeout(function() {
  const script = document.createElement('script');
  script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
  script.addEventListener('load', () => wxoLoader.init());
  document.head.appendChild(script);
}, 0);
</script>

​
Enabling Secure Embed Flow

To enable security for the Embed experience, follow the steps below using the Embed Settings API:

1

(Optional): Get Embed Config

curl -X GET 'http://localhost:4321/api/v1/private/embed/config' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <WXO_JWT>'
2

Generate IBM Public Key

curl -X POST 'http://localhost:4321/api/v1/private/embed/generate-key-pair' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <WXO_JWT>' \
  -d ''
3

Generate RS256 Key Pair

For more information, see Generating an RS256 key pair.

If you are only developing, you can use an RSA Key generator, such as CryptoTools.

This will generate the Client Public Key and Client Private Key.

4

Set Embed Config

curl -X POST 'http://localhost:4321/api/v1/private/embed/config' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <WXO_JWT>' \
  -H 'Content-Type: application/json' \
  -d '{
    "public_key": "<IBM Public Key from Step 2>",
    "client_public_key": "<Client Public Key from Step 3>",
    "is_security_enabled": true
}'

These are internal APIs available only in Developer Edition. For SaaS, they need to be exposed via the API Proxy for customer use.