> ## 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.

# Establishing Channels

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.

<Tabs>
  <Tab title="Importing from a file">
    Create a channel by using a YAML, JSON, or Python file:

    ```bash BASH theme={null}
    orchestrate channels import \
      --agent-name <agent_name> \
      --env <environment> \
      --file <file_path>
    ```

    <Expandable title="command flags">
      <ResponseField name="--agent-name" type="string" required={true}>
        The agent name.
      </ResponseField>

      <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
        The environment name. Possible values: `draft` or `live`.
      </ResponseField>

      <ResponseField name="--file / -f" type="string" required={true}>
        The path to the channel configuration file.
      </ResponseField>
    </Expandable>

    <Note>
      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.
    </Note>

    ### Channel configuration file formats

    Define channels by using YAML, JSON, or Python formats. Environment variables are supported.

    <CodeGroup>
      ```yaml YAML theme={null}
      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"
      ```

      ```json JSON theme={null}
      {
        "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"
      }
      ```

      ```python Python theme={null}
      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"
      )
      ```
    </CodeGroup>

    <Expandable title="detailed parameter descriptions">
      <ResponseField name="name" type="string">
        The channel name.
      </ResponseField>

      <ResponseField name="description" type="string">
        A brief description of the channel purpose.
      </ResponseField>

      <ResponseField name="channel" type="enum">
        The channel type. Possible values: `webchat`, `twilio_whatsapp`, `twilio_sms`, or `byo_slack`.
      </ResponseField>

      <ResponseField name="spec_version" type="string">
        The specification version.
      </ResponseField>

      <ResponseField name="kind" type="string">
        The resource type.
      </ResponseField>

      <ResponseField name="Extra fields" type="any">
        Channel-specific fields such as authentication fields.
      </ResponseField>
    </Expandable>

    <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 you cannot define two Twilio WhatsApp channels in the same environment.
    </Note>
  </Tab>

  <Tab title="Using CLI">
    Create a channel from the command line.

    ```bash BASH  theme={null}
    orchestrate channels create \
      --agent-name <agent_name> \
      --env <environment> \
      --type <channel_type> \
      --name <channel_name> \
      --description <channel_description> \
      --field <custom_field>=<custom_field_value>
    ```

    <Expandable title="command flags">
      <ResponseField name="--agent-name" type="string" required={true}>
        The agent name.
      </ResponseField>

      <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
        The environment name. Possible values: `draft` or `live`.
      </ResponseField>

      <ResponseField name="--type / -t" type="string" post={['values: webchat, twilio_whatsapp, twilio_sms, byo_slack']} required={true}>
        The channel type. Possible values: `webchat`, `twilio_whatsapp`, `twilio_sms`, or `byo_slack`.
      </ResponseField>

      <ResponseField name="--name / -n" type="string" required={true}>
        The channel name.
      </ResponseField>

      <ResponseField name="--description / -d" type="string" required={true}>
        A brief description of the channel purpose.
      </ResponseField>

      <ResponseField name="--field / -f" type="string">
        Channel-specific fields in key=value format. You can use this flag multiple times. <br /> <b>Example:</b> `--field account_sid=ACxxx --field twilio_authentication_token=xxx`
      </ResponseField>

      <ResponseField name="--output / -o" type="string">
        Write the channel specification to a file instead of creating the channel directly.
      </ResponseField>
    </Expandable>
  </Tab>
</Tabs>

***

## List channels

### List supported channel types

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

```bash BASH theme={null}
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 BASH theme={null}
orchestrate channels list-channels \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --verbose
```

<Expandable title="command flags">
  <ResponseField name="--agent-name" type="string" required={true}>
    The agent name.
  </ResponseField>

  <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
    The environment name. Possible values: `draft` or `live`.
  </ResponseField>

  <ResponseField name="--type / -t" type="string">
    Filter by channel type.
  </ResponseField>

  <ResponseField name="--verbose / -v" type="boolean">
    Show full JSON output.
  </ResponseField>
</Expandable>

***

## Get channel details

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

```bash BASH theme={null}
orchestrate channels get \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --verbose
```

<Expandable title="command flags">
  <ResponseField name="--agent-name" type="string" required={true}>
    The agent name.
  </ResponseField>

  <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
    The environment name. Possible values: `draft` or `live`.
  </ResponseField>

  <ResponseField name="--type / -t" type="string">
    The channel type.
  </ResponseField>

  <ResponseField name="--id / -i" type="string">
    The channel ID. Either ID or name is required.
  </ResponseField>

  <ResponseField name="--name / -n" type="string">
    The channel name. Either ID or name is required.
  </ResponseField>

  <ResponseField name="--verbose / -v" type="boolean">
    Show full JSON output.
  </ResponseField>
</Expandable>

<Note>
  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.
</Note>

***

## Export channels

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

```bash BASH theme={null}
orchestrate channels export \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --output <output_path>
```

<Expandable title="command flags">
  <ResponseField name="--agent-name" type="string" required={true}>
    The agent name.
  </ResponseField>

  <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
    The environment name. Possible values: `draft` or `live`.
  </ResponseField>

  <ResponseField name="--type / -t" type="string">
    The channel type.
  </ResponseField>

  <ResponseField name="--id / -i" type="string">
    The channel ID. Either ID or name is required.
  </ResponseField>

  <ResponseField name="--name / -n" type="string">
    The channel name. Either ID or name is required.
  </ResponseField>

  <ResponseField name="--output / -o" type="string">
    The path where the channel file will be saved.
  </ResponseField>
</Expandable>

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 behavior protects your credentials from accidental exposure. You must manually add these values when you import the channel into a new environment.
</Note>

***

## Delete channels

To delete a channel, run the following command:

```bash BASH theme={null}
orchestrate channels delete \
  --agent-name <agent_name> \
  --env <environment> \
  --type <channel_type> \
  --name <channel_name> \
  --id <channel_id> \
  --yes
```

<Expandable title="command flags">
  <ResponseField name="--agent-name" type="string" required={true}>
    The agent name.
  </ResponseField>

  <ResponseField name="--env / -e" type="string" post={['values: draft, live']} required={true}>
    The environment name. Possible values: `draft` or `live`.
  </ResponseField>

  <ResponseField name="--type / -t" type="string" post={['values: webchat, twilio_whatsapp, twilio_sms, byo_slack']} required={true}>
    The channel type. Possible values: `webchat`, `twilio_whatsapp`, `twilio_sms`, or `byo_slack`.
  </ResponseField>

  <ResponseField name="--id / -i" type="string">
    The channel ID.
  </ResponseField>

  <ResponseField name="--name / -n" type="string">
    The channel name.
  </ResponseField>

  <ResponseField name="--yes / -y" type="boolean">
    Skip confirmation prompt.
  </ResponseField>
</Expandable>

<Warning>
  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.
</Warning>

***

## 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.

* [Web chat](./web_chat)
* [Twilio WhatsApp](./twilio_whatsapp)
* [Twilio SMS](./twilio_sms)
* [Slack](./slack)
* [Genesys Bot Connector](./genesys_bot_connector)
* [Microsoft Teams](./microsoft_teams)
* [Facebook Messenger](./facebook_messenger)

***

## 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 BASH theme={null}
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