Establishing Channels - IBM watsonx Orchestrate ADK

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

Prerequisites

Before you establish channels, ensure that 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

Create channels

Create channels directly by using the ADK CLI or by importing a channel configuration file.

Importing from a file
Using CLI

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

BASH

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

Show command flags

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--file / -f

string

required

The path to the channel configuration file.

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

Channel configuration file formats

Define channels by using YAML, JSON, or Python formats. Environment variables are 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"

{
  "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"
}

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"
)

Show detailed parameter descriptions

name

string

The channel name.

description

string

A brief description of the channel purpose.

channel

enum

The channel type. Possible values: 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.

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 you cannot define 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

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--type / -t

string

required

values: webchat, twilio_whatsapp, twilio_sms, byo_slack

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

--name / -n

string

required

The channel name.

--description / -d

string

required

A brief description of the channel purpose.

--field / -f

string

Channel-specific fields in key=value format. You can use this flag multiple times.
Example: --field account_sid=ACxxx --field twilio_authentication_token=xxx

--output / -o

string

Write the channel specification to a file instead of creating the channel directly.

List channels

List supported channel types

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

BASH

orchestrate channels list

List channels for an agent

To list all channels that are 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

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--type / -t

string

Filter by channel type.

--verbose / -v

boolean

Show full JSON output.

Get 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

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--type / -t

string

The channel type.

--id / -i

string

The channel ID. Either ID or name is required.

--name / -n

string

The channel name. Either ID or name is required.

--verbose / -v

boolean

Show full JSON output.

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

Export 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

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--type / -t

string

The channel type.

--id / -i

string

The channel ID. Either ID or name is required.

--name / -n

string

The channel name. Either ID or name is required.

--output / -o

string

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

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

Delete 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

--agent-name

string

required

The agent name.

--env / -e

string

required

values: draft, live

The environment name. Possible values: draft or live.

--type / -t

string

required

values: webchat, twilio_whatsapp, twilio_sms, byo_slack

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

--id / -i

string

The channel ID.

--name / -n

string

The channel name.

--yes / -y

boolean

Skip confirmation prompt.

When you delete a channel, it stops receiving messages from the external platform immediately. You cannot undo this action. Ensure that you want to remove the channel before you proceed.

Channel types

Use channel integrations to connect an agent to external communication platforms. Each channel type has its own set of requirements and integration steps.

Understand 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

Best practices

Security

Store credentials securely by using environment variables or a secret manager
Do not commit credentials to version control
Rotate credentials regularly
Use different credentials for draft and live environments

Environment management

Test each channel in the draft environment before you move it to the live environment
Apply consistent naming conventions across environments
Document channel configurations so that your team can review and reuse them

​Prerequisites

​Create channels

​Channel configuration file formats

​List channels

​List supported channel types

​List channels for an agent

​Get channel details

​Export channels

​Delete channels

​Channel types

​Understand event URLs

​Event URL format

​Viewing event URLs

​Best practices

​Security

​Environment management

Prerequisites

Create channels

Channel configuration file formats

List channels

List supported channel types

List channels for an agent

Get channel details

Export channels

Delete channels

Channel types

Understand event URLs

Event URL format

Viewing event URLs

Best practices

Security

Environment management