The ChatBotKit Terraform Provider enables you to manage your AI chatbot infrastructure using Terraform. Define bots, datasets, skillsets, integrations, and more through declarative configuration files, enabling version control, automated deployments, and infrastructure consistency across environments.

Key Features

• Infrastructure as Code: Manage ChatBotKit resources declaratively
• Full Resource Coverage: Support for bots, datasets, skillsets, integrations, and more
• Data Sources: Read existing resources for reference in configurations
• Import Support: Bring existing resources under Terraform management
• State Management: Track resource changes and drift detection
• CI/CD Integration: Automate deployments through pipelines

Installation

From Terraform Registry

Add the provider to your Terraform configuration:

terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {
  # API key can be set here or via CHATBOTKIT_API_KEY env var
}
hcl

Then initialize Terraform:

terraform init
bash

Requirements

• Terraform 1.0 or higher
• A ChatBotKit API key from the Dashboard

Authentication

Configure authentication using either method:

Environment Variable (Recommended for CI/CD):

export CHATBOTKIT_API_KEY="your-api-key"
bash

Provider Configuration:

provider "chatbotkit" {
  api_key = var.chatbotkit_api_key
}

variable "chatbotkit_api_key" {
  type      = string
  sensitive = true
}
hcl

Quick Start

Here's a complete example that creates a knowledge-based support bot:

terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {}

# Create a knowledge base
resource "chatbotkit_dataset" "knowledge" {
  name        = "Product Knowledge Base"
  description = "Contains product documentation and FAQs"
}

# Create a skillset for tools
resource "chatbotkit_skillset" "tools" {
  name        = "Support Tools"
  description = "Tools for customer support operations"
}

# Add an ability to the skillset
resource "chatbotkit_skillset_ability" "ticket_lookup" {
  skillset_id = chatbotkit_skillset.tools.id
  name        = "lookup_ticket"
  description = "Look up a support ticket by ID"
  instruction = "Use this to find ticket details when a customer asks about their ticket status."
}

# Create the bot
resource "chatbotkit_bot" "support" {
  name        = "Customer Support Bot"
  description = "Handles customer inquiries"
  backstory   = "You are a helpful customer support agent for our company. Be friendly, professional, and always try to resolve issues on the first interaction."
  model       = "claude-4.5-sonnet"
  
  dataset_id  = chatbotkit_dataset.knowledge.id
  skillset_id = chatbotkit_skillset.tools.id
  
  moderation = true
  privacy    = true
}

# Deploy to Slack
resource "chatbotkit_slack_integration" "support_slack" {
  name   = "Support Slack Bot"
  bot_id = chatbotkit_bot.support.id
}

# Output the bot ID
output "bot_id" {
  value = chatbotkit_bot.support.id
}
hcl

Deploy with:

terraform plan    # Preview changes
terraform apply   # Apply changes
bash

Resources

The provider supports the following resources for creating and managing ChatBotKit entities:

Core Resources

Integration Resources

Data Sources

Read existing resources without managing them:

# Reference an existing bot
data "chatbotkit_bot" "existing" {
  id = "bot_abc123"
}

# Use its properties
output "existing_bot_name" {
  value = data.chatbotkit_bot.existing.name
}
hcl

Available data sources:

• chatbotkit_bot
• chatbotkit_dataset
• chatbotkit_blueprint
• chatbotkit_skillset

Resource Examples

Bot with Full Configuration

resource "chatbotkit_bot" "advanced" {
  name        = "Enterprise Assistant"
  description = "Multi-purpose enterprise bot"
  backstory   = <<-EOT
    You are an enterprise assistant with access to company knowledge 
    and various tools. Always be professional and helpful.
    
    Key guidelines:
    - Verify user identity for sensitive operations
    - Escalate complex issues to human agents
    - Log all significant interactions
  EOT
  
  model       = "claude-4.5-sonnet"
  dataset_id  = chatbotkit_dataset.knowledge.id
  skillset_id = chatbotkit_skillset.tools.id
  
  moderation = true
  privacy    = true
  visibility = "private"
  
  meta = {
    environment = "production"
    team        = "customer-success"
    version     = "2.0"
  }
}
hcl

Dataset with Records

resource "chatbotkit_dataset" "faq" {
  name        = "FAQ Database"
  description = "Frequently asked questions"
  
  meta = {
    source     = "zendesk"
    sync_daily = "true"
  }
}
hcl

Skillset with Multiple Abilities

resource "chatbotkit_skillset" "crm_tools" {
  name        = "CRM Tools"
  description = "Customer relationship management tools"
}

resource "chatbotkit_skillset_ability" "create_ticket" {
  skillset_id = chatbotkit_skillset.crm_tools.id
  name        = "create_support_ticket"
  description = "Create a new support ticket"
  instruction = "Use this when a customer needs to file a new support request."
}

resource "chatbotkit_skillset_ability" "update_contact" {
  skillset_id = chatbotkit_skillset.crm_tools.id
  name        = "update_contact_info"
  description = "Update customer contact information"
  instruction = "Use this when a customer wants to update their email, phone, or address."
}
hcl

Multi-Channel Deployment

resource "chatbotkit_bot" "omnichannel" {
  name      = "Omnichannel Support"
  backstory = "You are a support agent available across all channels."
  model     = "claude-4.5-sonnet"
}

resource "chatbotkit_slack_integration" "slack" {
  name   = "Slack Support"
  bot_id = chatbotkit_bot.omnichannel.id
}

resource "chatbotkit_discord_integration" "discord" {
  name   = "Discord Support"
  bot_id = chatbotkit_bot.omnichannel.id
}

resource "chatbotkit_telegram_integration" "telegram" {
  name   = "Telegram Support"
  bot_id = chatbotkit_bot.omnichannel.id
}
hcl

Examples

A library of complete, runnable examples lives in the provider repository under examples/. Two are worth calling out:

• agent-framework — an autonomous agent authored as a project of files and provisioned end to end. The bot's backstory is read from instructions.md via file(); its toolset is built from ability packs (pack/shell for shell/file/import tools in an isolated workspace, pack/cbk/space/skills for discovering skills); skills live as skills/*/SKILL.md folders uploaded into the workspace under .skills/ with fileset + for_each; and it ships with a Slack channel, scheduled triggers, and a heartbeat whose instructions come from heartbeat.md.
• multi-tenant agents — one agent per customer, each isolated in its own sub-account, in two flavors: multi-tenant-agents-shared (the same agent for all) and multi-tenant-agents-per-customer (a bespoke agent per customer). See below.

Each example is a self-contained directory with its own README.md — copy one as a starting point.

Multi-Tenancy and Sub-Accounts

For multi-tenant or white-label products, give each customer their own isolated environment using ChatBotKit sub-accounts (partner users). Each sub-account has its own bots, datasets, conversations, integrations, and settings.

Operate on a sub-account with the provider's run_as attribute. You hold one partner/master token (via CHATBOTKIT_API_KEY) and select the sub-account by ID — run_as sends the X-RunAs-UserId header — so there are no per-customer tokens. This is the standard Terraform multi-account pattern (provider aliases, like the AWS provider's assume_role):

provider "chatbotkit" {
  alias  = "acme"
  run_as = var.acme_account_id # api_key from CHATBOTKIT_API_KEY
}

module "acme" {
  source        = "./modules/agent"
  providers     = { chatbotkit = chatbotkit.acme }
  customer_name = "Acme Corporation"
}
hcl

Add a customer by adding a provider alias and a module call — no for_each. Account IDs are not secret; only the master token is. The provider cannot create sub-accounts itself (that is the partner REST API, partner/user/create), so create them once in the dashboard or via the API. See the multi-tenant-agents-shared and multi-tenant-agents-per-customer examples for the full pattern.

Importing Existing Resources

Bring existing resources under Terraform management:

# Import a bot
terraform import chatbotkit_bot.my_bot bot_abc123def456

# Import a dataset
terraform import chatbotkit_dataset.my_dataset dataset_xyz789

# Import an integration
terraform import chatbotkit_slack_integration.my_slack slack_integration_123
bash

After importing, add the resource to your configuration to prevent Terraform from trying to delete it.

State Management

Remote State

For team collaboration, use remote state backends:

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "chatbotkit/terraform.tfstate"
    region = "us-east-1"
  }
}
hcl

Workspaces

Manage multiple environments with workspaces:

terraform workspace new staging
terraform workspace new production
terraform workspace select production
bash

resource "chatbotkit_bot" "support" {
  name = "Support Bot - ${terraform.workspace}"
  # ... other configuration
}
hcl

CI/CD Integration

GitHub Actions Example

name: Deploy ChatBotKit Infrastructure

on:
  push:
    branches: [main]
    paths: ['terraform/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.6.0
      
      - name: Terraform Init
        run: terraform init
        working-directory: terraform
      
      - name: Terraform Plan
        run: terraform plan -out=tfplan
        working-directory: terraform
        env:
          CHATBOTKIT_API_KEY: ${{ secrets.CHATBOTKIT_API_KEY }}
      
      - name: Terraform Apply
        run: terraform apply -auto-approve tfplan
        working-directory: terraform
        env:
          CHATBOTKIT_API_KEY: ${{ secrets.CHATBOTKIT_API_KEY }}
yaml

Best Practices

Use Variables for Reusability

variable "environment" {
  type    = string
  default = "development"
}

variable "bot_model" {
  type    = string
  default = "claude-4.5-sonnet"
}

resource "chatbotkit_bot" "support" {
  name  = "Support Bot - ${var.environment}"
  model = var.bot_model
}
hcl

Organize with Modules

terraform/ ├── main.tf ├── variables.tf ├── outputs.tf └── modules/ ├── support-bot/ │ ├── main.tf │ ├── variables.tf │ └── outputs.tf └── sales-bot/ └── ...

Use Lifecycle Rules

resource "chatbotkit_bot" "critical" {
  name = "Critical Production Bot"
  
  lifecycle {
    prevent_destroy = true
  }
}
hcl

Tag Resources with Metadata

locals {
  common_meta = {
    managed_by  = "terraform"
    environment = var.environment
    team        = var.team
  }
}

resource "chatbotkit_bot" "support" {
  name = "Support Bot"
  meta = local.common_meta
}
hcl

Troubleshooting

Common Issues

Authentication Errors:

Error: 401 Unauthorized

Verify your API key is set correctly via environment variable or provider configuration.

Resource Not Found:

Error: Resource not found

The resource may have been deleted outside of Terraform. Remove it from state with:

terraform state rm chatbotkit_bot.my_bot
bash

State Drift:

~ resource "chatbotkit_bot" "support" { ~ name = "Old Name" -> "New Name" }

Someone modified the resource outside Terraform. Run terraform apply to reconcile or update your configuration to match.

Debug Logging

Enable detailed logging:

export TF_LOG=DEBUG
terraform plan
bash

Additional Resources

• ChatBotKit Documentation
• Terraform Provider Registry
• GitHub Repository
• API Reference