How to define a Genesys Cloud queue with skills in Terraform using the CX as Code provider

StarAdmin · March 6, 2026, 9:00am

How to define a Genesys Cloud queue with skills in Terraform using the CX as Code provider

What You Will Build

You will create a Genesys Cloud queue with associated routing skills using the purecloudlabs/cx-as-code Terraform provider.
This tutorial uses the Genesys Cloud CX as Code provider to manage configuration state declaratively.
The implementation covers Terraform HCL configuration, state management, and error handling for dependency resolution.

Prerequisites

Terraform Version: 1.0+
Provider: purecloudlabs/cx-as-code version 1.18.0+
OAuth Scopes:
- queue:write (for creating/updating queues)
- routing:skill:read or routing:skill:write (if creating skills dynamically, though this tutorial assumes pre-existing skills)
External Dependencies:
- Terraform installed locally
- Access to a Genesys Cloud Organization with API credentials

Authentication Setup

The CX as Code provider uses OAuth2 Client Credentials flow. You must configure the provider block with your client ID, client secret, and environment.

Do not hardcode secrets in your Terraform files. Use environment variables or a secrets manager.

terraform {
  required_providers {
    gen = {
      source  = "purecloudlabs/cx-as-code"
      version = "1.18.0"
    }
  }
}

provider "gen" {
  # These values are expected in environment variables
  # GEN_CLIENT_ID, GEN_CLIENT_SECRET, GEN_ENVIRONMENT
  client_id      = var.client_id
  client_secret  = var.client_secret
  environment    = var.environment
}

Set the environment variables before running terraform plan or terraform apply.

export GEN_CLIENT_ID="your-client-id"
export GEN_CLIENT_SECRET="your-client-secret"
export GEN_ENVIRONMENT="mypurecloud.com"

Implementation

Step 1: Define Skills References

Queues require skills to route interactions. In Genesys Cloud, skills are global resources. You must know the skillId or skillName and the domainId (usually the org ID) to associate them with a queue.

If you do not have the skill IDs, you can use the gen_routing_skill data source to look them up by name. This is safer than hardcoding UUIDs.

data "gen_routing_skill" "support_skill" {
  name    = "General Support"
  domain_id = var.org_id
}

data "gen_routing_skill" "billing_skill" {
  name    = "Billing"
  domain_id = var.org_id
}

Expected Response:
The data source returns an object containing the id and name of the skill. Terraform uses this id to build the queue configuration.

Error Handling:
If the skill does not exist, Terraform will fail during the plan phase with a 404 Not Found. Ensure the skill exists in the Genesys Cloud admin console before proceeding.

Step 2: Create the Queue Resource

The gen_queue resource is the core object. You must define the name, skill_requirements, and routing_skills.

The routing_skills block is critical. It maps a skill to a priority and a percentage of capacity. This defines how much of the queue’s capacity is reserved for that specific skill.

resource "gen_queue" "support_queue" {
  name            = "Customer Support Queue"
  description     = "Primary queue for general customer support inquiries"
  enable_auto_answer = false
  enable_callback  = true
  enable_customer_hold_music = true
  empty_agent_hold_music_uri = "https://example.com/hold.mp3"
  member_flow      = "LongestIdleAgent"
  wrap_up_policy   = "Optional"
  
  # Define the skills required for agents in this queue
  skill_requirements {
    required = true
    skill {
      id   = data.gen_routing_skill.support_skill.id
      name = data.gen_routing_skill.support_skill.name
    }
  }

  # Define routing skills to allocate capacity
  routing_skills {
    skill {
      id   = data.gen_routing_skill.support_skill.id
      name = data.gen_routing_skill.support_skill.name
    }
    priority   = 1
    percentage = 100
  }

  # Optional: Add a second skill with lower priority
  routing_skills {
    skill {
      id   = data.gen_routing_skill.billing_skill.id
      name = data.gen_routing_skill.billing_skill.name
    }
    priority   = 2
    percentage = 50
  }
}

Explanation of Parameters:

enable_auto_answer: If true, the system will automatically answer calls. Set to false for standard IVR routing.
member_flow: Determines how agents are selected. LongestIdleAgent is common for fairness.
routing_skills: This block can be repeated. The priority field determines which skill is checked first. percentage defines the portion of the queue’s capacity reserved for that skill. The sum of percentages does not need to equal 100, but exceeding 100 can lead to over-allocation warnings.

Edge Cases:

If you remove a routing_skills block, Terraform will remove that skill from the queue in Genesys Cloud.
If you change the percentage, Terraform will update the queue configuration. This may cause a brief moment of unavailability for that skill while the configuration propagates.

Step 3: Add Queue Members (Optional but Recommended)

A queue is useless without agents. You can add users to the queue using the gen_queue_member resource.

resource "gen_queue_member" "agent_member" {
  queue_id = gen_queue.support_queue.id
  
  # Reference a user by email or ID
  user {
    id = var.agent_user_id
  }
  
  # Set the agent's rank in the queue
  rank = 1
  
  # Set the maximum number of concurrent conversations
  max_concurrent_conversations = 5
}

Error Handling:
If the user_id does not exist, Terraform will return a 400 Bad Request. Validate the user ID exists in the Genesys Cloud organization.

Complete Working Example

Below is a complete, copy-pasteable Terraform configuration. Save this as main.tf.

terraform {
  required_providers {
    gen = {
      source  = "purecloudlabs/cx-as-code"
      version = "1.18.0"
    }
  }
}

variable "client_id" {
  description = "Genesys Cloud OAuth Client ID"
  type        = string
  sensitive   = true
}

variable "client_secret" {
  description = "Genesys Cloud OAuth Client Secret"
  type        = string
  sensitive   = true
}

variable "environment" {
  description = "Genesys Cloud Environment (e.g., mypurecloud.com)"
  type        = string
  default     = "mypurecloud.com"
}

variable "org_id" {
  description = "Genesys Cloud Organization ID"
  type        = string
}

variable "agent_user_id" {
  description = "User ID of the agent to add to the queue"
  type        = string
}

provider "gen" {
  client_id      = var.client_id
  client_secret  = var.client_secret
  environment    = var.environment
}

# Data sources to look up existing skills
data "gen_routing_skill" "support_skill" {
  name    = "General Support"
  domain_id = var.org_id
}

data "gen_routing_skill" "billing_skill" {
  name    = "Billing"
  domain_id = var.org_id
}

# Create the Queue
resource "gen_queue" "support_queue" {
  name            = "Customer Support Queue"
  description     = "Primary queue for general customer support inquiries"
  enable_auto_answer = false
  enable_callback  = true
  enable_customer_hold_music = true
  empty_agent_hold_music_uri = "https://example.com/hold.mp3"
  member_flow      = "LongestIdleAgent"
  wrap_up_policy   = "Optional"
  
  skill_requirements {
    required = true
    skill {
      id   = data.gen_routing_skill.support_skill.id
      name = data.gen_routing_skill.support_skill.name
    }
  }

  routing_skills {
    skill {
      id   = data.gen_routing_skill.support_skill.id
      name = data.gen_routing_skill.support_skill.name
    }
    priority   = 1
    percentage = 100
  }

  routing_skills {
    skill {
      id   = data.gen_routing_skill.billing_skill.id
      name = data.gen_routing_skill.billing_skill.name
    }
    priority   = 2
    percentage = 50
  }
}

# Add an agent to the queue
resource "gen_queue_member" "agent_member" {
  queue_id = gen_queue.support_queue.id
  
  user {
    id = var.agent_user_id
  }
  
  rank = 1
  max_concurrent_conversations = 5
}

Run the following commands to apply the configuration:

terraform init
terraform plan
terraform apply

Common Errors & Debugging

Error: 404 Not Found on Skill Lookup

What causes it:
The gen_routing_skill data source cannot find a skill with the specified name in the domain_id.

How to fix it:

Verify the skill name in the Genesys Cloud Admin Console.
Ensure the domain_id variable matches your organization ID.
Check for typos in the skill name.

Code showing the fix:

# Corrected data source with exact name match
data "gen_routing_skill" "support_skill" {
  name    = "General Support" # Exact match required
  domain_id = var.org_id
}

Error: 400 Bad Request on Queue Creation

What causes it:
The routing_skills block has invalid parameters. Common issues include:

percentage greater than 100.
priority not being a positive integer.
Referencing a skill that does not exist.

How to fix it:

Ensure percentage is between 0 and 100.
Ensure priority is a unique positive integer for each routing_skills block.
Verify the skill IDs are valid.

Code showing the fix:

# Corrected routing_skills block
routing_skills {
  skill {
    id   = data.gen_routing_skill.support_skill.id
    name = data.gen_routing_skill.support_skill.name
  }
  priority   = 1
  percentage = 100 # Valid percentage
}

Error: 429 Too Many Requests

What causes it:
Genesys Cloud API rate limits are exceeded. This can happen if you are applying a large number of resources in parallel.

How to fix it:

Reduce the number of parallel operations in Terraform by setting parallelism = 1 in the provider block.
Wait and retry the terraform apply command.

Code showing the fix:

provider "gen" {
  client_id      = var.client_id
  client_secret  = var.client_secret
  environment    = var.environment
  parallelism    = 1 # Reduce parallelism to avoid rate limits
}

How to define a Genesys Cloud queue with skills in Terraform using the CX as Code provider

How to define a Genesys Cloud queue with skills in Terraform using the CX as Code provider

What You Will Build

Prerequisites

Authentication Setup

Implementation

Step 1: Define Skills References

Step 2: Create the Queue Resource

Step 3: Add Queue Members (Optional but Recommended)

Complete Working Example

Common Errors & Debugging

Error: 404 Not Found on Skill Lookup

Error: 400 Bad Request on Queue Creation

Error: 429 Too Many Requests

Official References