Create, configure, and manage phone configurations for your watsonx Orchestrate agents with the ADK.
Prerequisites Before you add phone configurations, make sure you have:
Installed and configured the watsonx Orchestrate ADK.
Created an agent in watsonx Orchestrate.
Access credentials for phone service providers such as Genesys Cloud.
Agent voice configuration set up for phone integration.
Creating phone configs You can create phone configs directly using the ADK CLI or by importing a phone configuration file.
Importing from a file
Using CLI
Create a phone config using a YAML, JSON, or Python file: orchestrate phone import \ --file < file_pat h >
The path to phone config specification file.
Note:
The import command creates a new phone config or updates an existing one based on the name. If a phone config with the same name exists, the command updates it using the new configuration.
Define phone configs using YAML, JSON, or Python formats (env variables supported). name : "Production Phone" description : "Main production phone integration" channel : "genesys_audio_connector" spec_version : "v1" kind : "phone" security : api_key : "your_genesys_api_key" client_secret : "your_genesys_client_secret"
Show detailed parameter descriptions
The name of the phone config.
A short summary of the phone config’s purpose.
The type of phone configuration. Possible values are: genesys_audio_connector.
The specification version.
The resource type (should be “phone”).
Phone configuration-specific security configuration, such as API keys and client secrets.
Note:
YAML and JSON files support one phone config per file. Python files support multiple phone config instances in one file. Phone configs are global resources, so any agent can attach to any phone config.
Create a phone config from the command line. orchestrate phone create \ --type < channel_typ e > \ --name < config_nam e > \ --description < config_descriptio n > \ --field < custom_fiel d > = < custom_field_valu e >
Filter by phone configuration type. Possible values are: genesys_audio_connector.
The name of the phone config. Either ID or name is required.
A short summary of the phone config’s purpose.
Phone configuration-specific fields in key=value format. You can use it multiple times. Example: --field security.api_key=xxx --field security.client_secret=xxx
Write the phone config specification to a file rather than creating the config directly.
Listing phone configs Listing supported phone configuration types To list all currently supported phone configuration types, run the following command:
Listing phone configs To list all phone configs, run the following command:
orchestrate phone list-configs \ --type < channel_typ e > \ --verbose
Filter by phone configuration type. Possible values are: genesys_audio_connector.
Getting phone config details To retrieve details of a specific phone config, run the following command:
orchestrate phone get \ --name < config_nam e > \ --verbose
The ID of the phone config. Either ID or name is required.
The name of the phone config. Either ID or name is required.
Note:
Sensitive credential fields such as API keys, secrets, and client secrets appear as null or blank values in the output. This protects your credentials from accidental exposure.
Exporting phone configs To export a phone config to a YAML file, run the following command:
orchestrate phone export \ --name < config_nam e > \ --output < output_pat h >
The ID of the phone config. Either ID or name is required.
The name of the phone config. Either ID or name is required.
The path where the phone config file will be saved.
Exporting phone configs helps you:
Back up your phone config definitions
Migrate phone configs between environments
Track changes through version control
Note:
Sensitive credential fields such as API keys, secrets, and client secrets 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 phone config into a new environment.
Deleting phone configs To delete a phone config, run the following command:
orchestrate phone delete \ --name < config_nam e > \ --yes
The ID of the phone config.
The name of the phone config.
Skip confirmation prompt.
Important:
When you delete a phone config, all agent attachments are removed and the phone integration stops working immediately. You cannot undo this action, so make sure you want to remove the phone config before you proceed.
Managing agent attachments Phone configs are global resources that agents can attach to. Multiple agents and environments can share the same phone config.
Attaching an agent to a phone config To attach an agent/environment to a phone config, run the following command:
orchestrate phone attach \ --name < config_nam e > \ --agent-name < agent_nam e > \ --env < environmen t >
The ID of the phone config. Either ID or name is required.
The name of the phone config. Either ID or name is required.
The name of the agent to attach.
The environment to attach. Possible values are: draft or live.
After attaching an agent, you’ll receive webhook configuration details needed to integrate with your phone provider.
Note:
The agent must have voice configuration set up for phone integration to work properly.
Detaching an agent from a phone config To detach an agent/environment from a phone config, run the following command:
orchestrate phone detach \ --name < config_nam e > \ --agent-name < agent_nam e > \ --env < environmen t >
The ID of the phone config. Either ID or name is required.
The name of the phone config. Either ID or name is required.
The name of the agent to detach.
The environment to detach. Possible values are: draft or live.
Listing attachments for a phone config To list all agent/environment attachments for a phone config, run the following command:
orchestrate phone list-attachments \ --name < config_nam e >
The ID of the phone config. Either ID or name is required.
The name of the phone config. Either ID or name is required.
Phone Configuration Types Genesys Audio Connector Connect your agent to Genesys Cloud using the Audio Connector integration.
Prerequisites
Genesys Cloud account
Genesys Audio Connector integration created
User-generated credentials:
API Key (any string you choose)
Client Secret (any string you choose, must be base-64 encoded)
Important: Both API Key and Client Secret are user-generated values (not obtained from Genesys Cloud). You create these values yourself. The same values must be configured in both:
Your ADK phone configuration
Your Genesys Audio Connector integration settings (go to the Credentials tab and add these values)
The Client Secret must be base-64 encoded. The API Key has no encoding restrictions. Creating a Genesys Audio Connector phone config Use one of the following methods to define the phone config:
Using CLI: orchestrate phone create \ --type genesys_audio_connector \ --name "Customer Support Phone" \ --description "Phone integration for customer support" \ --field api_key=your_api_key_here \ --field client_secret=your_client_secret_here
Using YAML: name : "Customer Support Phone" description : "Phone integration for customer support" channel : "genesys_audio_connector" spec_version : "v1" kind : "phone" security : api_key : "your_api_key_here" client_secret : "your_client_secret_here"
Using Python: from ibm_watsonx_orchestrate.agent_builder.phone import GenesysAudioConnectorChannel phone = GenesysAudioConnectorChannel( name = "Customer Support Phone" , description = "Phone integration for customer support" , security = { "api_key" : "your_api_key_here" , "client_secret" : "your_client_secret_here" } )
Configuration requirements Field Required Format Description security.api_keyYes String User-generated API key security.client_secretYes String (base-64 encoded) User-generated client secret, base-64 encoded
Generating secure values: You can generate secure random strings for API Key and Client Secret using tools like:
openssl rand -base64 32 (Linux/macOS) - automatically generates base-64 encoded output[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })) (PowerShell)Online generators
Understanding webhook configuration When you attach an agent to a phone config, the ADK provides webhook configuration details. Your phone provider uses this information to connect calls to your agent.
Viewing webhook configuration The webhook configuration is displayed when you attach an agent to a phone config:
orchestrate phone attach \ --name "Customer Support Phone" \ --agent-name my_agent \ --env live
Output:
Successfully attached agent 'my_agent' / environment 'live' to phone config. Webhook Configuration: Genesys Audio Connect URI: wss://channels.example.com/tenants/sub123_inst456/ Connector ID: agents/agent-789/environments/env-012/channels/genesys_audio_connector/abc-123/connect
Configuring Genesys Cloud Use the webhook configuration values in your Genesys Audio Connector settings:
Log into your Genesys Cloud admin portal
Enter the Audio Connect URI in the Base Connection URI field in Genesys Cloud Admin / Integrations
Enter the Connector ID in the Architect Inbound Call Flow / Audio Connector
