Contribute in GitHub:

Configuring multiple service providers

Using JSON configuration properties, you can configure IBM® Voice Gateway to support multiple service providers for each of the Watson services that it depends on. With multiple service providers, Voice Gateway can use a backup service if a failure occurs in any of the supporting services. Multi-provider configuration is only supported by using JSON configuration, and isn't configurable through environment variables.

Before you begin

Learn about how to use JSON configuration and create a tenant configuration JSON file. For more information, see Configuring tenants in a multi-tenant JSON configuration.

Deploy your multi-tenant JSON configuration. See Deploying a multi-tenant JSON configuration.

Create multiple instances of your Watson service instances in different geographic regions, for disaster recovery.

Speech to Text
Text to Speech (self-service only)
IBM Watson™ Assistant (self-service only)

Or, create third-party speech recognition (speech-to-text) and speech synthesis (text-to-speech) services. See Integrating third-party speech services

Configuring multiple providers

You can configure multiple providers for each service that supports Voice Gateway. See the following sections for configuration file examples for each service.

* [Watson Assistant](#multi-assistant)
* [Dynamically configuring multiple Watson Assistant services](#multi-dynamic)
* [Speech to Text](#multi-stt)
* [Connecting with the speech-to-text adapter](#multi-sttadapter)
* [Text to Speech](#multi-tts)
* [Connect with a text-to-speech adapter](#multi-ttsadapter)
* [Monitor performance with Call Detail Records (CDR) event reports](#multi-monitoring)

The provider selection policy

You can define the order of configured providers that Voice Gateway uses as a back up if the original service fails during a call by using the providerSelectionPolicy property. In Version 1.0.0.6, only the sequential policy is supported.

sequential: Voice Gateway starts with the service listed first in the JSON configuration file, then moves to the second service if the first one fails. Voice Gateway tries service providers in the order that they are listed until reaching the end of the list.

Configuring multiple Watson Assistant service providers

The following code example shows the configuration for multiple Watson Assistant services with token authentication enabled, one in Dallas and a backup in Washington DC.

  "conversation": {
    "providerSelectionPolicy" : "sequential",
    "providers": [
        {
        "name": "dallas",
        "providerType": "watson",
        "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
        "password": "Qa55C0s473",
        "username": "8yw76lm-n5op-43q2-1098-r7s6tu543457",
        "tokenAuthEnabled": true,
        "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
        "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
        }
        {
          "name" : "washington-dc",
          "providerType": "watson",
          "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
          "workspaceID": "z26hg87f-d456-91a2-k999-1a0bc9d87e6f",
          "password": "Pa55C0d345",
          "username": "9j8k76lm-n5op-43q2-1098-r7s6tu543210",
          "tokenAuthEnabled": true,
          "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
          "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
        }
    ]
  }

Dynamically configuring multiple Watson Assistant services

You can also dynamically configure multiple providers in the vgwActSetConversationConfig command when switching to a new Watson Assistant service during a call. See Dynamically configuring multiple Watson Assistant services for code examples and more information about dynamically configuring your Watson Assistant services.

Configuring multiple Speech to Text service providers

You can customize each service instance by including properties at the provider level. Or, you can apply definitions across all providers by configuring properties such as config and broadbandConfig at the root level of the node.

The following code example shows how to configure multiple Speech to Text service providers for your Voice Gateway. Each provider will use the same config and broadbandConfig definitions.

 "stt": {
    "config": {
        "model": "en-US_NarrowbandModel",
        "profanity_filter": true,
        "smart_formatting": true,
        "x-watson-learning-opt-out": true,
        "max_alternatives": 2.0
    },
    "broadbandConfig": {
      "model": "en-US_BroadbandModel",
      "profanity_filter": true,
      "smart_formatting": true,
      "x-watson-learning-opt-out": true,
      "max_alternatives": 2.0
    },
    "providerSelectionPolicy" : "sequential",
    "providers" : [
        {
          "name" : "dallas",
          "credentials": {
            "url": "https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}",
            "username": "8yw76lm-n5op-43q2-1098-r7s6tu543457",
            "password": "Qa55C0s473",
            "tokenAuthEnabled": true,
            "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
            "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
          },
          "config": {
            "customization_id": "34a5678-bc90-12d3-ef4g-56hij7k8l90m"
          },
          "broadbandConfig": {
            "customization_id": "34a5678-bc90-12d3-ef4g-56hij7k8l90m"
          }
        },
        {
          "name" : "washington-dc",
          "credentials": {
            "url": "https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}",
            "username": "9j8k76lm-n5op-43q2-1098-r7s6tu543210",
            "password": "Pa55C0d345",
            "tokenAuthEnabled": true,
            "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
            "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
          },
          "config": {
            "customization_id": "34a5678-bc90-12d3-ef4g-56hij7k8l90m"
          },
          "broadbandConfig": {
            "customization_id": "34a5678-bc90-12d3-ef4g-56hij7k8l90m"
          }
        }
    ]
  }

Connecting with the speech-to-text adapter

If you connect Voice Gateway to a speech to text adapter, you can set the thirdPartyCredentials option at the provider level to integrate your external services with Voice Gateway.

 "stt": {
    "credentials": {
      "url": "https://localhost:4000",
      "username": "myUsername",
      "password": "myPassword"
    },
    "config": {
       "languageCode": "en-US"
    },
    "broadbandConfig": {
       "languageCode": "en-US"
    },
    "providerSelectionPolicy" : "sequential",
    "providers" : [
        {
          "name" : "google-south",
          "thirdPartyCredentials": {
                "type": "service_account",
                "project_id": "my_google_project",
                "private_key_id": "d2e45f67gh8i90123j4klm565opq7rs8901t1234",
                "private_key": "-----BEGIN PRIVATE ... \n-----END PRIVATE KEY-----\n",
                "client_email": "developer1@my_google_project.iam.gserviceaccount.com",
                "client_id": "100033044440506077880901",
                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                "token_uri": "https://accounts.google.com/o/oauth2/token",
                "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/developer1@my_google_project.iam.gserviceaccount.com"
           }
        },
        {
          "name" : "google-west",
          "thirdPartyCredentials": {
                "type": "service_account",
                "project_id": "my_google_project",
                "private_key_id": "d2e45f67gh8i90123j4klm565opq7rs8901t1234",
                "private_key": "-----BEGIN PRIVATE ... \n-----END PRIVATE KEY-----\n",
                "client_email": "developer1@my_google_project.iam.gserviceaccount.com",
                "client_id": "100033044440506077880901",
                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                "token_uri": "https://accounts.google.com/o/oauth2/token",
                "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/developer1@my_google_project.iam.gserviceaccount.com"
           }
        }
    ]
  }

Configuring multiple Text to Speech service providers

The following code example shows how to configure multiple Text to Speech service providers for your Voice Gateway.

{
    "tts": {
    "config": {
        "voice": "en-US_MichaelVoice"
    },
    "providerSelectionPolicy" : "sequential",
    "providers" : [
        {
          "name" : "dallas",
          "credentials": {
            "url": "https://api.us-south.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}",
            "username": "8yw76lm-n5op-43q2-1098-r7s6tu543457",
            "password": "Qa55C0s473",
            "tokenAuthEnabled": true,
            "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
            "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
          }
        },
        {
          "name" : "washington-dc",
          "credentials": {
            "url": "https://api.us-south.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}",
            "username": "9j8k76lm-n5op-43q2-1098-r7s6tu543210",
            "password": "Pa55C0d345",
            "tokenAuthEnabled": true,
            "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token",
            "tokenServiceUrl": "https://iam.cloud.ibm.com/identity/token"
          }
        }
    ]
  }
}

Connecting with a text-to-speech adapter

If you connect Voice Gateway to a text-to-speech adapter, you can set the thirdPartyCredentials option at the provider level to integrate your external services with Voice Gateway.

{
    "tts": {
      "credentials": {
        "url": "https://localhost:4000",
        "username": "myUsername",
        "password": "myPassword"
      },
      "config": {
        "voice": "en-US_MichaelVoice"
      },
      "providerSelectionPolicy" : "sequential",
      "providers" : [
          {
            "thirdPartyCredentials": {
                  "type": "service_account",
                  "project_id": "my_google_project",
                  "private_key_id": "d2e45f67gh8i90123j4klm565opq7rs8901t1234",
                  "private_key": "-----BEGIN PRIVATE ... \n-----END PRIVATE KEY-----\n",
                  "client_email": "developer1@my_google_project.iam.gserviceaccount.com",
                  "client_id": "100033044440506077880901",
                  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                  "token_uri": "https://accounts.google.com/o/oauth2/token",
                  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/developer1@my_google_project.iam.gserviceaccount.com"
             }
          },
          {
            "thirdPartyCredentials": {
                  "type": "service_account",
                  "project_id": "my_google_project",
                  "private_key_id": "d2e45f67gh8i90123j4klm565opq7rs8901t1234",
                  "private_key": "-----BEGIN PRIVATE ... \n-----END PRIVATE KEY-----\n",
                  "client_email": "developer1@my_google_project.iam.gserviceaccount.com",
                  "client_id": "100033044440506077880901",
                  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                  "token_uri": "https://accounts.google.com/o/oauth2/token",
                  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/developer1@my_google_project.iam.gserviceaccount.com"
             }
          }
      ]
    }
}

Monitoring performance with Call Detail Records

Call Detail Record (CDR) events include which provider was used during a call. You can examine the CDR event report to see the providers used in a call and the order they were used.

Note: The ttsProvidersUsed field might be returned as empty if only the text to speech cache was used.

Each entry is an array of providers used during the call, in the order that they were used. See Reporting call detail record events from Voice Gateway. The following example shows how providers are recorded in a CDR event report.

"event": {
    "conversationProvidersUsed" : ["dallas"],
    "sttProvidersUsed" : ["dallas"],
    "ttsProvidersUsed" : ["dallas","washington-dc"]
}