GitHubContribute in GitHub: Edit online

copyright: years: 2017, 2023 lastupdated: "2023-01-03"

Configuring tenants in a multi-tenant JSON configuration

Although similar in concept, configuring a Voice Gateway environment with JSON configuration properties differs from single-tenant configuration in its implementation because the tenant configuration is separated from the server configuration.

  • Single-tenant environment: Voice Gateway is configured through Docker environment variables unless further altered using the API.
  • Multi-tenant JSON configuration: Tenant configuration is specified and stored in a separate JSON file, which is then referenced in the Voice Gateway configuration. Configuration that isn't related to a tenant, such as server configuration, is specified through Docker environment variables. By specifying tenant configuration as JSON objects, distinct configuration settings can be mapped to each individual tenant.

When you configure Voice Gateway with JSON configuration properties, only calls to the specified tenants can connect, effectively whitelisting the configured tenants. For calls to connect, the SIP To header field or Request-URI value in the SIP INVITE request that starts the call must contain the entire phone number or other value defined as the tenantURI in the JSON file. If someone attempts to call a tenant that isn't defined, Voice Gateway rejects the call.

Configuring multitenancy with JSON properties is supported in Version 1.0.0.2 and later.

Configuring tenants

  1. Create a JSON file that contains the configuration for one or more tenants.

    Tip: To quickly get started, copy and paste the contents of the tenantConfig.json sample file into an empty JSON file. Then edit the file and add the configuration for each tenant.

    Within a main tenants object, specify a list of tenant objects. Each tenant can contain the following keys:

    • tenantURI: A unique tenant identifier, such as a phone number. Must match the SIP To URI in the SIP INVITE request that starts the call. Required.
    • description: A description of the tenant, such as how it's used. Optional, but recommended.
    • Other optional tenant configuration properties that define settings for the particular tenant.
    • conversation: A JSON object of configuration properties for Watson Assistant. Optional.
    • stt: A JSON object of configuration properties for the IBM Speech to Text service or third-partyspeech recognition services enabled by the Speech to Text Adapter. Optional.
    • tts: A JSON object of configuration properties for the IBM Text to Speech service. Optional.
    • reporting: A JSON object of configuration properties for publishing reporting events. Optional.
    • mediaEncryption: A JSON object of configuration properties that are for securing media streams. Optional.
    • SMSpipe: A JSON object of configuration properties for integrating SMS Gateway support for Voice Gateway. Optional.

    In the conversation, stt, tts, and reporting objects, you can further configure the related service or reporting events. For a full list of properties and sample JSON configuration file, see Advanced JSON configuration properties.

    For example, the following JSON configures a tenant at the number 234-555-6789 as a self-service agent, plus another tenant at 234-555-7890 on the myhost.com host whose details are not shown.

{ "tenants": [ { "tenantURI": "2345556789", "description": "Voice Gateway Demo US", "whitelistFromUri" : "8765554321", "putCallerOnHoldOnTransfer" : "false", "conversation": { "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}", "workspaceID": "a23de67h-e527-40d5-a867-5c0ce9e72d0d", "apikey": "{apikey}", "tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token" }, }, { " tenantURI":"2345557890@myhost.com" ... } ] } 


1. Add your tenant configuration to the Voice Gateway configuration, and deploy your environment. For more information, see [Deploying a multi-tenant JSON configuration](https://www.ibm.com/docs/en/voice-gateway?topic=configuration-deploying-multi-tenant-json).

## Tenant configuration properties {: #multi-config-props}

You can find information about tenant configuration properties in [Advanced JSON configuration properties](https://www.ibm.com/docs/en/voice-gateway?topic=reference-advanced-json-configuration-properties).