Documentation Index Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
Use this file to discover all available pages before exploring further.
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: orchestrate channels import \ --agent-name < agent_nam e > \ --env < environmen t > \ --file < file_pat h >
--env / -e
string
required
values: draft, live
The environment name. Possible values: draft or live.
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.
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"
Show detailed parameter descriptions
A brief description of the channel purpose.
The channel type. Possible values: webchat, twilio_whatsapp, twilio_sms, or byo_slack.
The specification version.
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. orchestrate channels create \ --agent-name < agent_nam e > \ --env < environmen t > \ --type < channel_typ e > \ --name < channel_nam e > \ --description < channel_descriptio n > \ --field < custom_fiel d > = < custom_field_valu e >
--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.
A brief description of the channel purpose.
Channel-specific fields in key=value format. You can use this flag multiple times. Example: --field account_sid=ACxxx --field twilio_authentication_token=xxx
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:
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:
orchestrate channels list-channels \ --agent-name < agent_nam e > \ --env < environmen t > \ --type < channel_typ e > \ --verbose
--env / -e
string
required
values: draft, live
The environment name. Possible values: draft or live.
Get channel details To retrieve details of a specific channel, run the following command:
orchestrate channels get \ --agent-name < agent_nam e > \ --env < environmen t > \ --type < channel_typ e > \ --name < channel_nam e > \ --verbose
--env / -e
string
required
values: draft, live
The environment name. Possible values: draft or live.
The channel ID. Either ID or name is required.
The channel name. Either ID or name is required.
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:
orchestrate channels export \ --agent-name < agent_nam e > \ --env < environmen t > \ --type < channel_typ e > \ --name < channel_nam e > \ --output < output_pat h >
--env / -e
string
required
values: draft, live
The environment name. Possible values: draft or live.
The channel ID. Either ID or name is required.
The channel name. Either ID or name is required.
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:
orchestrate channels delete \ --agent-name < agent_nam e > \ --env < environmen t > \ --type < channel_typ e > \ --name < channel_nam e > \ --id < channel_i d > \ --yes
--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.
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.
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:
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
