Establishing Channels - IBM watsonx Orchestrate ADK

Create, configure, and manage channels for your watsonx Orchestrate agents with the ADK.

Prerequisites

Before you establish channels, make sure you have:

Installed and configured the watsonx Orchestrate ADK.
Created an agent in watsonx Orchestrate.
Access credentials for external services such as Twilio, Slack, and Genesys.

Creating channels

You can create channels directly using the ADK CLI or by importing a channel configuration file.

Importing from a file
Using CLI

Create a channel using a YAML, JSON, or Python file:

BASH

orchestrate channels import \
  --agent-name <agent_name> \
  --env <environment> \
  --file <file_path>

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—file (-f)	string	Yes	The path to channel configuration file.

Note: The import command creates a new channel or updates an existing one based on the name. If a channel with the same name exists, the command updates it using the new configuration.

Channel configuration file formats

Define channels using YAML, JSON, or Python formats (env variables supported).

name: "WhatsApp Support"
description: "Customer support via WhatsApp"
channel: "twilio_whatsapp"
spec_version: "v1"
kind: "channel"
account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
twilio_authentication_token: "your_auth_token_here"

Show detailed parameter descriptions

name

string

The name of the channel.

description

string

A short summary of the channel’s purpose.

channel

enum

The type of channel. Possible values are: webchat, twilio_whatsapp, twilio_sms, or byo_slack.

spec_version

string

The specification version.

kind

string

The resource type.

Extra fields

any

Channel-specific fields, such as authentication fields.

Note: YAML and JSON files support one channel specification per file. Python files support multiple channel instances in one file. You can define only one instance per channel type in each environment. For example, you can define both a Twilio WhatsApp channel and a Slack channel, but not two Twilio WhatsApp channels in the same environment.

Create a channel from the command line.

BASH

orchestrate channels create \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --description <channel_description> \
  --field <custom_field>=<custom_field_value>

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—type (-t)	string	Yes	The type of channel. Possible values are: `webchat`, `twilio_whatsapp`, `twilio_sms`, or `byo_slack`.
—name (-n)	string	Yes	The name of the channel.
—description (-d)	string	No	A short summary of the channel’s purpose.
—field (-f)	string	No	Channel-specific fields in key=value format. You can use it multiple times. Example: `--field account_sid=ACxxx --field twilio_authentication_token=xxx`
—output (-o)	string	No	Write the channel specification to a file rather than creating the channel directly.

Listing channels

Listing supported channel types

To list all currently supported channel types, run the following command:

BASH

orchestrate channels list

Listing channels for an agent

To list all channels configured for a specific agent and environment, run the following command:

BASH

orchestrate channels list-channels \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --verbose

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—type (-t)	string	No	Filter by channel type.
—verbose (-v)	-	No	Show full JSON output.

Getting channel details

To retrieve details of a specific channel, run the following command:

BASH

orchestrate channels get \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --verbose

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—type (-t)	string	No	The type of the channel.
—id (-i)	string	No	The ID of the channel. Either ID or name is required.
—name (-n)	string	No	The name of the channel. Either ID or name is required.
—verbose (-v)	-	No	Show full JSON output.

Note: Sensitive credential fields such as authentication tokens, secrets, and passwords appear as null or blank values in the output. This protects your credentials from accidental exposure.

Exporting channels

To export a channel configuration to a YAML file, run the following command:

BASH

orchestrate channels export \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --output <output_path>

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—type (-t)	string	No	The type of the channel.
—id (-i)	string	No	The ID of the channel. Either ID or name is required.
—name (-n)	string	No	The name of the channel. Either ID or name is required.
—output (-o)	string	No	The path where the channel file will be saved.

Exporting channel configurations helps you:

Back up your channel definitions
Migrate channels between environments
Track changes through version control

Note: Sensitive credential fields such as authentication tokens, secrets, and passwords appear as null or blank values in the exported file. This protects your credentials from accidental exposure. You need to manually add these values when importing the channel into a new environment.

Deleting channels

To delete a channel, run the following command:

BASH

orchestrate channels delete \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --id <channel_id> \
  --yes

Show command flags

Flag	Type	required	Description
—agent-name	string	Yes	The name of the agent.
—env(-e)	string	Yes	The name of the environment. Possible values are: `draft` or `live`.
—type (-t)	string	Yes	The type of the channel. Possible values are: `webchat`, `twilio_whatsapp`, `twilio_sms`, or `byo_slack`.
—id (-i)	string	No	The ID of the channel.
—name (-n)	string	No	The name of the channel.
—yes (-y)	-	No	Skip confirmation prompt.

Important: When you delete a channel, it stops receiving messages from the external platform immediately. You cannot undo this action, so make sure you want to remove the channel before you proceed.

Channel Types

Web chat

Use web chat to embed a chat widget in your website or web application.

Note: Web chat uses a dedicated workflow. Unlike other channel types, you manage web chat channels with a specialized command. Standard operations such as create, list-channels, get, export, and delete do not apply. For full integration steps, see Agent Integration Guide.

Quick start: Generating web chat embed code

To integrate web chat with your agent, use the dedicated web chat embed command:

BASH

orchestrate channels webchat embed \
  --agent-name my_agent \
  --env live

This command generates a HTML and JavaScript code that you can add to your website to embed the chat widget.

What you receive

The embed code includes:

A pre-configured chat widget
Automatic connection to your agent
Responsive design for desktop and mobile
Options to customize appearance and behavior

Next steps for web chat

For detailed instructions on:

Customizing the web chat appearance
Configuring advanced settings
Troubleshooting common issues

See the comprehensive Agent Integration Guide.

Twilio WhatsApp

Integrate your agent with WhatsApp Business using Twilio’s API.

Prerequisites

Twilio account with WhatsApp API access
Twilio Account SID
Twilio Authentication Token

Creating a Twilio WhatsApp channel

Use one of the following methods to define the channel: Using CLI:

BASH

orchestrate channels create \
  --agent-name my_agent \
  --env live \
  --type twilio_whatsapp \
  --name "WhatsApp Support" \
  --field account_sid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --field twilio_authentication_token=your_auth_token_here

Using YAML:

name: "WhatsApp Support"
description: "Customer support via WhatsApp"
channel: "twilio_whatsapp"
spec_version: "v1"
kind: "channel"
account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
twilio_authentication_token: "your_auth_token_here"

Using Python:

from ibm_watsonx_orchestrate.agent_builder.channels import TwilioWhatsappChannel

whatsapp = TwilioWhatsappChannel(
    name="WhatsApp Support",
    description="Customer support via WhatsApp",
    account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    twilio_authentication_token="your_auth_token_here"
)

Configuration requirements

Field	Required	Format	Description
`account_sid`	Yes	String	Your Twilio Account SID
`twilio_authentication_token`	Yes	String	Your Twilio Authentication Token

Twilio SMS

Enable SMS messaging for your agent using Twilio.

Prerequisites

Twilio account
Twilio Account SID
Twilio Authentication Token
Twilio phone number

Creating a Twilio SMS channel

Using CLI:

BASH

orchestrate channels create \
  --agent-name my_agent \
  --env live \
  --type twilio_sms \
  --name "SMS Support" \
  --field account_sid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --field twilio_authentication_token=your_auth_token_here \
  --field phone_number=+1234567890

Using YAML:

name: "SMS Support"
description: "Customer support via SMS"
channel: "twilio_sms"
spec_version: "v1"
kind: "channel"
account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
twilio_authentication_token: "your_auth_token_here"
phone_number: "+1234567890"

Using Python:

from ibm_watsonx_orchestrate.agent_builder.channels import TwilioSMSChannel

sms = TwilioSMSChannel(
    name="SMS Support",
    description="Customer support via SMS",
    account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    twilio_authentication_token="your_auth_token_here",
    phone_number="+1234567890"
)

Configuration requirements

Field	Required	Format	Description
`account_sid`	Yes	String	Your Twilio Account SID
`twilio_authentication_token`	Yes	String	Your Twilio Authentication Token
`phone_number`	No	String	Twilio phone number for SMS

Slack

Deploy your agent to Slack workspaces using your own Slack app.

Prerequisites

Slack workspace with admin access
Slack app created in your workspace
Slack API credentials:
- Client ID
- Client Secret
- Signing Secret
- Bot User OAuth Token for each team/workspace
- Slack Team ID (Starts with the letter ‘T’)
  - Locate your team ID in the URL of the Workflow Steps tab in your Slack app settings
Slack Bot Token Scopes:
- app_mentions:read
- chat:write
- im:history
- im:write
- users.profile:read
Subscribed to following Bot Events:
- message.im
- app_mention

Creating a Slack channel

Using YAML:

name: "Slack Support Bot"
description: "Support agent in Slack"
channel: "byo_slack"
spec_version: "v1"
kind: "channel"
client_id: "1234567890.1234567890"
client_secret: "your_client_secret_here"
signing_secret: "your_signing_secret_here"
teams:
  - id: "T01234567"
    bot_access_token: "xoxb-your-bot-token-here"

Using Python:

from ibm_watsonx_orchestrate.agent_builder.channels import SlackChannel, SlackTeam

slack = SlackChannel(
    name="Slack Support Bot",
    description="Support agent in Slack",
    client_id="1234567890.1234567890",
    client_secret="your_client_secret_here",
    signing_secret="your_signing_secret_here",
    teams=[
        SlackTeam(
            id="T01234567",
            bot_access_token="xoxb-your-bot-token-here"
        )
    ]
)

Configuration requirements

Field	Required	Format	Description
`client_id`	Yes	String	Slack API client ID
`client_secret`	Yes	String	Slack API client secret
`signing_secret`	Yes	String	Slack API signing secret
`teams`	Yes	Array of SlackTeam objects	Slack teams or workspaces
`teams[].id`	Yes	String	Slack team or workspace ID
`teams[].bot_access_token`	Yes	String	Bot user OAuth token

Genesys Bot Connector

Connect your agent to Genesys Cloud using the Bot Connector integration. For detailed setup instructions, see Integrating Genesys Bot Connector in the IBM watsonx Orchestrate documentation.

Prerequisites

Genesys Cloud account
Genesys Bot Connector integration created
Genesys Cloud credentials:
- Client ID (from Genesys OAuth)
- Client Secret (from Genesys OAuth)
- Bot Connector ID (from Genesys Integration)
- API URL (from Genesys Cloud Platform API)
User-defined verification token:
- Verification Token (any secure random string you choose)

Important: The Verification Token is not obtained from Genesys Cloud. You create this value yourself (it can be any secure random string). You must configure this same value in both:

Your ADK channel configuration (as verification_token)
Your Genesys Cloud Bot Connector integration settings (go to the Credentials tab and add a key-value pair: key=x-watson-genesys-verification-token, value=your random string)

Creating a Genesys Bot Connector channel

Use one of the following methods to define the channel: Using YAML:

name: "Genesys Contact Center Bot"
description: "Agent for Genesys Cloud"
channel: "genesys_bot_connector"
spec_version: "v1"
kind: "channel"
client_id: "12345678-1234-1234-1234-123456789abc"
client_secret: "your_client_secret_here"
verification_token: "your_verification_token_here"
bot_connector_id: "87654321-4321-4321-4321-cba987654321"
api_url: "https://api.mypurecloud.com"

Using Python:

from ibm_watsonx_orchestrate.agent_builder.channels import GenesysBotConnectorChannel

genesys = GenesysBotConnectorChannel(
    name="Genesys Contact Center Bot",
    description="Agent for Genesys Cloud",
    client_id="12345678-1234-1234-1234-123456789abc",
    client_secret="your_client_secret_here",
    verification_token="your_verification_token_here",
    bot_connector_id="87654321-4321-4321-4321-cba987654321",
    api_url="https://api.mypurecloud.com"
)

Configuration requirements

Field	Required	Format	Description
`client_id`	Yes	String	Genesys Cloud client ID (from OAuth section)
`client_secret`	Yes	String	Genesys Cloud client secret (from OAuth section)
`verification_token`	Yes	String	User-defined token string (must match the value set in Genesys Bot Connector Credentials tab with key `x-watson-genesys-verification-token`)
`bot_connector_id`	Yes	String	Integration ID from Genesys Bot Connector
`api_url`	Yes	String	Genesys API Server URI. For example: `https://api.mypurecloud.com`

Generating verification token: You can generate a secure random string for verification_token using tools like:

openssl rand -base64 32 (Linux/macOS)
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })) (PowerShell)
Online UUID generators or password generators

Remember to use the same value in your ADK configuration and in the Genesys Bot Connector Credentials tab (with key x-watson-genesys-verification-token).

Understanding event URLs

When you create a channel, the ADK provides an event URL. External platforms use this URL to send messages to your agent.

Event URL format

https://channels.{instance_environment}/tenants/{tenant_id}/agents/{agent_id}/environments/{env_id}/channels/{channel_type}/{channel_id}/events

Viewing event URLs

The event URL is displayed when you create or import a channel:

BASH

orchestrate channels import \
  --agent-name my_agent \
  --env live \
  --file channel.yaml

Output:

Creating new channel 'WhatsApp Support'...
Successfully created channel 'WhatsApp Support'. id: 'abc123'
Event URL: https://channels.example.com/tenants/tenant123/agents/agent456/environments/env789/channels/twilio_whatsapp/abc123/events

Release Notes

Get Started

Build

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate MCP Server

Reference

Legal notices

​Prerequisites

​Creating channels

​Channel configuration file formats

​Listing channels

​Listing supported channel types

​Listing channels for an agent

​Getting channel details

​Exporting channels

​Deleting channels

​Channel Types

​Web chat

​Quick start: Generating web chat embed code

​What you receive

​Next steps for web chat

​Twilio WhatsApp

​Prerequisites

​Creating a Twilio WhatsApp channel

​Configuration requirements

​Twilio SMS

​Prerequisites

​Creating a Twilio SMS channel

​Configuration requirements

​Slack

​Prerequisites

​Creating a Slack channel

​Configuration requirements

​Genesys Bot Connector

​Prerequisites

​Creating a Genesys Bot Connector channel

​Configuration requirements

​Understanding event URLs

​Event URL format

​Viewing event URLs

​Best practices

​Security

​Environment management

Prerequisites

Creating channels

Channel configuration file formats

Listing channels

Listing supported channel types

Listing channels for an agent

Getting channel details

Exporting channels

Deleting channels

Channel Types

Web chat

Quick start: Generating web chat embed code

What you receive

Next steps for web chat

Twilio WhatsApp

Prerequisites

Creating a Twilio WhatsApp channel

Configuration requirements

Twilio SMS

Prerequisites

Creating a Twilio SMS channel

Configuration requirements

Slack

Prerequisites

Creating a Slack channel

Configuration requirements

Genesys Bot Connector

Prerequisites

Creating a Genesys Bot Connector channel

Configuration requirements

Understanding event URLs

Event URL format

Viewing event URLs

Best practices

Security

Environment management