Terraform Provider

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:

Then initialize Terraform:

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

Provider Configuration:

Quick Start

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

Deploy with:

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:

Available data sources:

• chatbotkit_bot
• chatbotkit_dataset
• chatbotkit_blueprint
• chatbotkit_skillset

Resource Examples

Bot with Full Configuration

Dataset with Records

Skillset with Multiple Abilities

Multi-Channel Deployment

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

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:

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:

Workspaces

Manage multiple environments with workspaces:

CI/CD Integration

GitHub Actions Example

Best Practices

Use Variables for Reusability

Organize with Modules

Use Lifecycle Rules

Tag Resources with Metadata

Troubleshooting

Common Issues

Authentication Errors:

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

Resource Not Found:

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

State Drift:

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

Debug Logging

Enable detailed logging:

Additional Resources

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