←back to docs

Terraform Provider

ChatBotKit Terraform Provider allows you to manage your AI chatbot infrastructure as code. Learn how to install, configure, and use the provider to deploy bots, datasets, skillsets, and integrations.

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.

Features

The ChatBotKit Terraform Provider offers several powerful features for infrastructure management:

FeatureDescription
Infrastructure as CodeManage ChatBotKit resources declaratively
Full Resource CoverageSupport for bots, datasets, skillsets, integrations, and more
Data SourcesRead existing resources for reference in configurations
Import SupportBring existing resources under Terraform management
State ManagementTrack resource changes and drift detection
CI/CD IntegrationAutomate deployments through pipelines

Installation

Add the provider to your Terraform configuration:

Then initialize Terraform:

Requirements

To use the ChatBotKit Terraform Provider, you need:

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

Authentication

Configure authentication using either method:

Environment Variable (Recommended):

Provider Configuration:

When both are set, the provider configuration takes precedence over the environment variable.

Quick Start

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

Deploy with:

Resources

The provider supports the following resources:

Core Resources

ResourceDescription
chatbotkit_botAI chatbot agents with configurable models and behaviors
chatbotkit_datasetKnowledge bases for retrieval-augmented generation
chatbotkit_skillsetCollections of abilities (tools) for bots
chatbotkit_skillset_abilityIndividual abilities within a skillset
chatbotkit_blueprintReusable templates for bot configurations
chatbotkit_secretSecure credential storage
chatbotkit_fileFile records for uploads used by datasets and abilities
chatbotkit_file_contentUploads content (inline, local, or remote URL) to a file
chatbotkit_spaceIsolated, persistent filesystem (workspace) for agents
chatbotkit_space_storage_fileA file stored at a path within a space
chatbotkit_portalCustomer-facing portal configurations
chatbotkit_policyData-retention and usage policies for bots and blueprints

Integrations

ResourceDescription
chatbotkit_widget_integrationEmbeddable website chat widget
chatbotkit_slack_integrationSlack workspace integration
chatbotkit_discord_integrationDiscord bot deployment
chatbotkit_microsoftteams_integrationMicrosoft Teams integration
chatbotkit_googlechat_integrationGoogle Chat integration
chatbotkit_telegram_integrationTelegram bot deployment
chatbotkit_whatsapp_integrationWhatsApp Business integration
chatbotkit_messenger_integrationFacebook Messenger integration
chatbotkit_instagram_integrationInstagram messaging integration
chatbotkit_email_integrationEmail-based interactions
chatbotkit_twilio_integrationTwilio SMS/voice integration
chatbotkit_support_integrationSupport/helpdesk integration
chatbotkit_notion_integrationNotion workspace sync
chatbotkit_sitemap_integrationWebsite content ingestion
chatbotkit_extract_integrationStructured data extraction from conversations
chatbotkit_mcpserver_integrationModel Context Protocol (MCP) server endpoint
chatbotkit_trigger_integrationScheduled or event-driven bot triggers

Data Sources

Read existing resources without managing them:

Available data sources: chatbotkit_bot, chatbotkit_dataset, chatbotkit_blueprint, chatbotkit_skillset.

Bot Resource Example

MCP Server Integration Example

Expose a skillset as an MCP endpoint for AI clients like Claude Desktop or VSCode:

Trigger Integration Example

Schedule a bot to run on a cron schedule:

Extract Integration Example

Extract structured data from conversations:

Importing Resources

Bring existing resources under Terraform management:

Examples

A library of complete, runnable examples lives in the provider repository under examples/. Highlights:

  • agent-framework - an autonomous agent authored as a project of files (instructions, skills, heartbeat) and provisioned end to end: a bot whose backstory is read from instructions.md, ability packs (pack/shell, pack/cbk/space/skills), an isolated workspace with file-based skills uploaded under .skills/, a Slack channel, and both scheduled triggers and a heartbeat.
  • 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 Multi-Tenancy below.
  • Focused references for datasets, skillsets, dynamic skills, MCP servers, multi-agent workflows, and more.

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

Multi-Tenancy and Sub-Accounts

To give each customer their own isolated environment, ChatBotKit's partner API creates sub-accounts (partner users), each with its own bots, datasets, conversations, and settings. Operate on a sub-account with the provider's run_as attribute: you hold one partner/master token and select the sub-account by ID (it 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), so create them once in the dashboard or via partner/user/create. See the multi-tenant-agents-shared and multi-tenant-agents-per-customer examples.

CI/CD Integration

Example GitHub Actions workflow for automated deployments:

Best Practices

  1. Use Variables: Parameterize your configurations for reusability across environments
  2. Remote State: Use remote backends (S3, Terraform Cloud) for team collaboration
  3. Workspaces: Manage multiple environments (dev, staging, prod) with workspaces
  4. Lifecycle Rules: Use prevent_destroy for critical production resources
  5. Metadata: Tag resources with meta for organization and filtering

Additional Resources

ChatBotKitterraforminfrastructure as codedevopsIaCautomationdeployment