Adding Phone Configurations

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

BASH

orchestrate phone import \
  --file <file_path>

Show command flags

--file / -f

string

required

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.

Create a phone config from the command line:

BASH

orchestrate phone create \
  --type <channel_type> \
  --name <config_name> \
  --description <config_description> \
  --field <key>=<value>

Show command flags

Phone configuration type: genesys_audio_connector or sip_trunk.

The name of the phone config.

A short summary of the phone config’s purpose.

Configuration-specific fields in key=value format. Can be used multiple times.

Write the phone config specification to a file rather than creating the config directly.

Note: For complex SIP configurations with multiple fields, consider using the import command with a YAML file for better readability.

Listing phone configs

Listing supported phone configuration types

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

BASH

orchestrate phone list

Listing phone configs

To list all phone configs, run the following command:

BASH

orchestrate phone list-configs \
  --type <channel_type> \
  --verbose

Show command flags

--type / -t

string

Filter by phone configuration type. Possible values are: genesys_audio_connector, sip_trunk.

--verbose / -v

boolean

Show full JSON output.

Getting phone config details

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

BASH

orchestrate phone get \
  --name <config_name> \
  --verbose

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

--verbose / -v

boolean

Show full JSON output.

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:

BASH

orchestrate phone export \
  --name <config_name> \
  --output <output_path>

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

--output / -o

string

The pat

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:

BASH

orchestrate phone delete \
  --name <config_name> \
  --yes

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

--yes / -y

boolean

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.

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 in Genesys Cloud
(Optional) User-generated credentials if you want to provide your own:
- 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). If you don’t provide them, they will be automatically generated for you and displayed in the command output.If you choose to create your own credentials, 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.

Configuration file formats

Define Genesys phone configs using YAML, JSON, or Python formats. Credentials are optional and will be auto-generated if not provided:

spec_version: v1
kind: phone
service_provider: genesys_audio_connector
name: "Customer Support Phone"
description: "Phone integration for customer support"
# security field is optional - credentials will be auto-generated if left blank

spec_version: v1
kind: phone
service_provider: genesys_audio_connector
name: "Customer Support Phone"
description: "Phone integration for customer support"
security:
  api_key: "your_api_key_here"
  client_secret: "your_base64_encoded_secret_here"

{
  "spec_version": "v1",
  "kind": "phone",
  "service_provider": "genesys_audio_connector",
  "name": "Customer Support Phone",
  "description": "Phone integration for customer support",
  "security": {
    "api_key": "your_api_key_here",
    "client_secret": "your_base64_encoded_secret_here"
  }
}

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

Configuration fields

Show detailed parameter descriptions

spec_version

string

required

The specification version. Use v1.

kind

string

required

The resource type. Must be phone.

service_provider

string

required

Must be genesys_audio_connector for Genesys configurations.

name

string

required

The name of the phone config (max 64 characters).

description

string

A short summary of the phone config’s purpose (max 1024 characters).

security

object

Security credentials for Genesys Audio Connector. Optional - if not provided, credentials will be auto-generated and displayed in the command output.Optional fields:

api_key (string): Custom API key (auto-generated if not provided)
client_secret (string): Custom client secret, must be base-64 encoded (auto-generated if not provided)

Creating the phone config

Using import command:

BASH

orchestrate phone import \
  --file genesys_phone_config.yaml

Using CLI create command (with auto-generated credentials):

BASH

orchestrate phone create \
  --type genesys_audio_connector \
  --name "Customer Support Phone" \
  --description "Phone integration for customer support"

Output with auto-generated credentials:

[INFO] - ====================
[INFO] - GENERATED CREDENTIALS - SAVE THESE!
[INFO] - Please paste these credentials in:
[INFO] -   Genesys Audio Connector > Integration Settings > Credentials tab
[INFO] -
[INFO] - API Key: qG_pQts1PJKsOfBvDZQ3nA
[INFO] - Client Secret: 4yJmW/TSahU6TVbodqGlJw==
[INFO] -
[INFO] - ====================

[INFO] - Creating new phone config 'Customer Support Phone'...
[INFO] - Successfully created phone config 'Customer Support Phone'. id: 'abc-123-def-456'

Using CLI create command (with custom credentials):

BASH

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_base64_encoded_secret_here

Credentials: Auto-generated credentials are recommended for simplicity and security. If you need to provide custom credentials, you can generate secure random strings using:

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)

Important: Auto-generated credentials are only displayed once during creation. Save them immediately to configure in Genesys Cloud.

Managing agent attachments

Genesys Audio Connector uses agent attachments to connect your phone config to specific agents. When you attach an agent, you receive webhook configuration details that you’ll configure in Genesys Cloud.

Genesys Audio Connector Only: The attach, detach, and list-attachments commands are only used with Genesys Audio Connector configurations. SIP trunk configurations use phone number management instead (see SIP Trunk section below).

Attaching an agent

After creating the phone config, attach an agent to start receiving calls:

BASH

orchestrate phone attach \
  --name "Customer Support Phone" \
  --agent-name my_agent \
  --env live

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

--agent-name

string

The name of the agent to attach.

--env / -e

string

The environment to attach. Possible values are: draft or 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

Note: The agent must have voice configuration set up for phone integration to work properly.

Detaching an agent

To detach an agent/environment from a phone config:

BASH

orchestrate phone detach \
  --name "Customer Support Phone" \
  --agent-name my_agent \
  --env live

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

--agent-name

string

The name of the agent to detach.

--env / -e

string

The environment to detach. Possible values are: draft or live.

Listing attachments

To list all agent/environment attachments for a phone config:

BASH

orchestrate phone list-attachments \
  --name "Customer Support Phone"

Show command flags

--id / -i

string

The ID of the phone config. Either ID or name is required.

--name / -n

string

The name of the phone config. Either ID or name is required.

Configuring Genesys Cloud

Use the webhook configuration values from the attach command in your Genesys Audio Connector settings:

Log into your Genesys Cloud admin portal
Navigate to Admin → Integrations
Find your Audio Connector integration
Go to the Configuration tab:
- Enter the Audio Connect URI in the “Base Connection URI” field
Go to the Credentials tab:
- Add the api_key and client_secret values (either auto-generated from the creation output or your custom values)
In Architect, configure your Inbound Call Flow:
- Add an “Audio Connector” action
- Enter the Connector ID in the connector ID field

Note: The webhook configuration is displayed when you attach an agent. You can also retrieve it later using orchestrate phone get --name "Customer Support Phone". However, credentials are only shown during initial creation for security reasons.

SIP Trunk

Connect your agent to SIP providers (e.g. Twilio).

Prerequisites

SIP trunk provider account
(Optional) SIP authentication credentials
Phone numbers provisioned with your SIP provider

Configuration file formats

Define SIP phone configs using YAML, JSON, or Python formats:

spec_version: v1
kind: phone
service_provider: sip_trunk
name: "SIP Phone Channel"
description: "Enterprise SIP trunk integration"
# Security is required - must explicitly set secure_trunking and authentication
security:
  secure_trunking: true  # Enable TLS/SIPS
  authentication: true   # Enable SIP authentication
  username: "your_sip_username"  # Required if authentication: true
  password: "your_sip_password"  # Required if authentication: true
# Optional: Custom SIP headers
custom_invite_headers:
  - name: "X-Custom-Header"
  - name: "From"
  - name: "To"
# Optional: Call behavior settings
put_caller_on_hold_on_transfer: true
send_provisional_response: true
# Optional: Error handling configuration
error_handling:
  fallback_sip_uri: "sip:fallback@domain.com"
  transfer_failure:
    reply_message: "Your call could not be transferred to a live agent. Please try again later. Thank you. Goodbye."
    disconnect_call: true
  call_failure:
    reply_message: "There's been a problem with the call. You're being transferred to a live agent now."

{
  "spec_version": "v1",
  "kind": "phone",
  "service_provider": "sip_trunk",
  "name": "SIP Phone Channel",
  "description": "Enterprise SIP trunk integration",
  "security": {
    "secure_trunking": true,
    "authentication": true,
    "username": "your_sip_username",
    "password": "your_sip_password"
  },
  "custom_invite_headers": [
    {"name": "X-Custom-Header"},
    {"name": "From"},
    {"name": "To"}
  ],
  "put_caller_on_hold_on_transfer": true,
  "send_provisional_response": true,
  "error_handling": {
    "fallback_sip_uri": "sip:fallback@domain.com",
    "transfer_failure": {
      "reply_message": "Your call could not be transferred to a live agent. Please try again later. Thank you. Goodbye.",
      "disconnect_call": true
    },
    "call_failure": {
      "reply_message": "There's been a problem with the call. You're being transferred to a live agent now."
    }
  }
}

from ibm_watsonx_orchestrate.agent_builder.phone import SIPTrunkChannel

phone = SIPTrunkChannel(
    name="SIP Phone Channel",
    description="Enterprise SIP trunk integration",
    # Security is required
    security={
        "secure_trunking": True,  # Enable TLS/SIPS
        "authentication": True,   # Enable SIP authentication
        "username": "your_sip_username",  # Required if authentication: True
        "password": "your_sip_password"   # Required if authentication: True
    },
    # Optional fields
    custom_invite_headers=[
        {"name": "X-Custom-Header"},
        {"name": "From"},
        {"name": "To"}
    ],
    put_caller_on_hold_on_transfer=True,
    send_provisional_response=True,
    error_handling={
        "fallback_sip_uri": "sip:fallback@domain.com",
        "transfer_failure": {
            "reply_message": "Your call could not be transferred to a live agent. Please try again later. Thank you. Goodbye.",
            "disconnect_call": True
        },
        "call_failure": {
            "reply_message": "There's been a problem with the call. You're being transferred to a live agent now."
        }
    }
)

Configuration fields

Show detailed parameter descriptions

spec_version

string

required

The specification version. Use v1.

kind

string

required

The resource type. Must be phone.

service_provider

string

required

Must be sip_trunk for SIP trunk configurations.

name

string

required

The name of the phone config (max 64 characters).

description

string

A short summary of the phone config’s purpose (max 1024 characters).

custom_invite_headers

array

List of custom SIP INVITE headers to include in outbound calls. Each header must have a name field.Common headers include:

From - Override the From header
To - Override the To header
Custom headers (e.g., X-Custom-Header)

put_caller_on_hold_on_transfer

boolean

When true, puts the caller on hold during live agent transfer. Default is false.

send_provisional_response

boolean

When true, sends SIP provisional responses (e.g., 180 Ringing, 183 Session Progress). Default is false.

security

object

required

Security configuration for SIP trunk authentication and encryption. This field is required.Required fields:

secure_trunking (boolean): Enable TLS/SIPS encryption. Must be explicitly set to true or false.
authentication (boolean): Enable SIP authentication. Must be explicitly set to true or false.

Conditional fields (required only if authentication: true):

username (string): SIP authentication username
password (string): SIP authentication password

Note: Even if you don’t want security, you must explicitly set secure_trunking: false and authentication: false.

error_handling

object

Configuration for handling call and transfer failures.Fields:

fallback_sip_uri (string): Fallback SIP URI to route calls when errors occur
transfer_failure (object): Configuration for transfer failure handling
- reply_message (string): Message to play when transfer fails
- disconnect_call (boolean): Whether to disconnect the call after playing the message
call_failure (object): Configuration for general call failure handling
- reply_message (string): Message to play when call encounters an error

Creating the phone config

You can create a SIP trunk phone config using either the import command or the CLI create command. Using import command:

BASH

orchestrate phone import \
  --file sip_phone_config.yaml

Using CLI create command: Basic SIP trunk (no security):

BASH

orchestrate phone create \
  --type sip_trunk \
  --name "My SIP Trunk" \
  --description "Basic SIP trunk without authentication" \
  --field 'security={"secure_trunking": false, "authentication": false}'

With authentication and secure trunking:

BASH

orchestrate phone create \
  --type sip_trunk \
  --name "My SIP Trunk" \
  --description "Fully secured SIP trunk" \
  --field 'security={"secure_trunking": true, "authentication": true, "username": "myuser", "password": "mypass"}'

With all options:

BASH

orchestrate phone create \
  --type sip_trunk \
  --name "SIP Phone Channel" \
  --description "Enterprise SIP trunk integration" \
  --field 'custom_invite_headers=[{"name": "X-Custom-Header"}, {"name": "From"}, {"name": "To"}]' \
  --field 'put_caller_on_hold_on_transfer=true' \
  --field 'send_provisional_response=true' \
  --field 'security={"secure_trunking": true, "authentication": true, "username": "USER", "password": "PASS"}' \
  --field 'error_handling={"fallback_sip_uri": "sip:username@domain.com", "transfer_failure": {"reply_message": "Please try again later.", "disconnect_call": true}, "call_failure": {"reply_message": "There has been a problem with the call."}}'

Output:

Successfully created phone config 'SIP Phone Channel'. id: 'abc-123-def-456'

Configure these values in your SIP trunk provider:
   Full SIP URI: 'sips:public.voip.dl.watson-orchestrate.ibm.com?x-tenant-id=subscription123_instance456'

Tip: For complex SIP configurations with many fields, using a YAML file with the import command is more readable and maintainable than using the CLI create command with JSON field values.

Getting SIP connection details

After creating a SIP trunk phone config, retrieve the SIP URI that your provider needs:

BASH

orchestrate phone get \
  --name "SIP Phone Channel"

Output:

Phone Config: SIP Phone Channel
  Type: sip_trunk
  ID: abc-123-def-456
  SIP URI: sips:public.voip.dl.watson-orchestrate.ibm.com?x-tenant-id=subscription123_instance456

Note: The SIP URI format is sips:FQDN?x-tenant-id=TENANT_ID where:

sips indicates secure SIP (TLS encryption)
The FQDN is environment-specific (e.g., public.voip.dl.watson-orchestrate.ibm.com)
The x-tenant-id parameter identifies your watsonx Orchestrate tenant

Managing phone numbers

SIP trunk configurations support phone number management, allowing you to associate specific phone numbers with your SIP config and optionally route them to specific agents.

SIP Trunk Only: Phone number management commands (add-number, list-numbers, update-number, delete-number) are only available for SIP trunk configurations. Genesys Audio Connector does not support these operations.

Adding a phone number

BASH

orchestrate phone add-number \
  --name "SIP Phone Channel" \
  --number "+15551234567" \
  --description "Customer support hotline" \
  --agent-name my_agent \
  --env live

Show command flags

--id (-i)

string

The ID of the phone config. Either ID or name is required.

--name (-n)

string

The name of the phone config. Either ID or name is required.

--number

string

required

Phone number in E.164 format (e.g., +15551234567)

--description (-d)

string

Description for the phone number

--agent-name

string

Agent name to associate with this phone number for routing

--env (-e)

string

Environment (draft or live) to associate with this phone number

Listing phone numbers

BASH

orchestrate phone list-numbers \
  --name "SIP Phone Channel"

Updating a phone number

BASH

orchestrate phone update-number \
  --name "SIP Phone Channel" \
  --number "+15551234567" \
  --description "Updated description" \
  --agent-name different_agent \
  --env draft

Show command flags

--id (-i)

string

The ID of the phone config. Either ID or name is required.

--name (-n)

string

The name of the phone config. Either ID or name is required.

--number

string

required

Phone number to update

--new-number

string

New phone number (if changing the number itself)

--description (-d)

string

New description

--agent-name

string

Agent name to associate with this phone number

--env (-e)

string

Environment (draft or live) to associate with this phone number

Deleting a phone number

BASH

orchestrate phone delete-number \
  --name "SIP Phone Channel" \
  --number "+15551234567" \
  --yes

Show command flags

--id (-i)

string

The ID of the phone config. Either ID or name is required.

--name (-n)

string

The name of the phone config. Either ID or name is required.

--number

string

required

Phone number to delete

--yes (-y)

Skip confirmation prompt

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Prerequisites

Creating phone configs

Listing phone configs

Listing supported phone configuration types

Listing phone configs

Getting phone config details

Exporting phone configs

Deleting phone configs

Phone Configuration Types

Genesys Audio Connector

Prerequisites

Configuration file formats

Configuration fields

Creating the phone config

Managing agent attachments

Attaching an agent

Detaching an agent

Listing attachments

Configuring Genesys Cloud

SIP Trunk

Prerequisites

Configuration file formats

Configuration fields

Creating the phone config

Getting SIP connection details

Managing phone numbers

Adding a phone number

Listing phone numbers

Updating a phone number

Deleting a phone number

​Prerequisites

​Creating phone configs

​Listing phone configs

​Listing supported phone configuration types

​Listing phone configs

​Getting phone config details

​Exporting phone configs

​Deleting phone configs

​Phone Configuration Types

​Genesys Audio Connector

​Prerequisites

​Configuration file formats

​Configuration fields

​Creating the phone config

​Managing agent attachments

Attaching an agent

Detaching an agent

Listing attachments

​Configuring Genesys Cloud

​SIP Trunk

​Prerequisites

​Configuration file formats

​Configuration fields

​Creating the phone config

​Getting SIP connection details

​Managing phone numbers

Adding a phone number

Listing phone numbers

Updating a phone number

Deleting a phone number

Prerequisites

Creating phone configs

Listing phone configs

Listing supported phone configuration types

Listing phone configs

Getting phone config details

Exporting phone configs

Deleting phone configs

Phone Configuration Types

Genesys Audio Connector

Prerequisites

Configuration file formats

Configuration fields

Creating the phone config

Managing agent attachments

Configuring Genesys Cloud

SIP Trunk

Prerequisites

Configuration file formats

Configuration fields

Creating the phone config

Getting SIP connection details

Managing phone numbers