Policies

Policies provide a powerful mechanism for automating data governance and compliance operations within your ChatBotKit platform. They enable you to define rules that automatically manage the lifecycle of conversations, messages, and other data according to your organizational requirements, legal obligations, and business policies.

Understanding Policy Types

Currently, only retention policies are available. Retention policies automatically manage how long data is kept before archival or deletion, helping you maintain compliance with data retention requirements and optimize storage usage.

Creating Policies

Creating a policy allows you to define automated rules for data management. Each policy requires a name, description, and a type that determines what kind of automated operation will be performed. The configuration object provides type-specific settings that control the policy's behavior.

POST /api/v1/policy/create
Content-Type: application/json

{
  "name": "30DayRetention",
  "description": "Automatically archive conversations older than 30 days",
  "type": "retention",
  "config": {}
}

http

Policy Configuration:

  • name: A descriptive name for the policy (required)
  • description: Detailed explanation of what the policy does (required)
  • type: The policy type (currently only "retention" is available)
  • config: Type-specific configuration object
  • blueprintId: Optional blueprint association for organized management
  • meta: Additional metadata for custom tracking and configuration

Configuration Object:

The config object contains policy-specific settings that control how the policy operates. The structure and required fields depend on the policy type being created.

Important Considerations:

  • Policies are evaluated and executed automatically by the platform
  • Changes to policy configuration affect future evaluations, not past actions
  • Multiple policies can coexist with different scopes and priorities
  • Policy execution is logged for compliance auditing purposes
  • Deleted data cannot be recovered - use archival when preservation is needed

Best Practices:

  • Start with archival policies before implementing deletion policies
  • Test policies with small scopes before applying broadly
  • Document policy purposes clearly for compliance requirements
  • Review policy effectiveness regularly and adjust configurations
  • Consider legal and regulatory requirements when setting retention periods

Listing Policies

Retrieve all policies configured in your account. Policies define rules and behaviors that govern how your conversational AI agents operate, including content moderation, response filtering, safety guidelines, and compliance requirements. This endpoint provides a comprehensive view of your policy landscape for audit, management, and configuration purposes.

GET /api/v1/policy/list
Authorization: Bearer YOUR_API_TOKEN

http

Response Format:

{
  "items": [
    {
      "id": "policy_abc123",
      "name": "30DayRetention",
      "description": "Automatically archive conversations older than 30 days",
      "type": "retention",
      "blueprintId": "blueprint_xyz789",
      "config": {},
      "meta": {},
      "createdAt": "2025-11-10T08:00:00Z",
      "updatedAt": "2025-11-15T14:30:00Z"
    }
  ]
}

json

Understanding Policy Types:

The type field indicates what kind of policy this is. Currently, only retention policies are available:

  • Retention: Data retention and cleanup policies for managing conversation lifecycle
  • Access: Access control and permission policies

Different policy types have different configuration structures in the config field, tailored to their specific purposes.

Policy Configuration:

The config field contains policy-specific settings as a JSON object. The structure varies by policy type and includes all the parameters that control how the policy operates. When listing policies, you can inspect these configurations to understand your current policy settings.

Query Parameters for Filtering:

  • cursor: Pagination cursor for retrieving subsequent pages
  • take: Number of policies to return per page
  • order: Sort order ("asc" or "desc", default is "desc")
  • type: Filter by specific policy type
  • blueprintId: Filter policies belonging to a specific blueprint
  • meta: Filter by metadata fields using JSON query syntax

Filtering by Policy Type:

To retrieve only policies of a specific type, use the type query parameter. This is useful when you want to review all moderation policies, compliance policies, or any other specific category:

GET /api/v1/policy/list?type=moderation

http

Filtering by Blueprint:

When working within the context of a specific project or blueprint, filter policies to see only those associated with that blueprint:

GET /api/v1/policy/list?blueprintId=blueprint_xyz789

http

Pagination:

For accounts with many policies, use cursor-based pagination to efficiently retrieve results:

GET /api/v1/policy/list?cursor=next_page_cursor&take=25

http

Policy Management Workflows:

Audit and Review: Periodically list all policies to ensure they align with current requirements and organizational standards. Review policy configurations to verify they're still appropriate for your use cases.

Blueprint Configuration: When setting up a new blueprint, list existing policies to identify which ones should be associated with the new project.

Compliance Verification: Filter by compliance policy types to generate reports for regulatory requirements or internal audits.

Policy Consolidation: Review all policies to identify duplicates or similar policies that could be consolidated for easier management.

Common Use Cases:

  • Policy Inventory: Get a complete view of all active policies
  • Compliance Auditing: Review policies for regulatory compliance
  • Security Review: Verify moderation and safety policies are configured
  • Blueprint Setup: Identify policies to attach to new projects
  • Policy Migration: Export policy configurations for environment migration
  • Access Control Review: Audit access policies for security assessment
  • Configuration Backup: Document policy settings for disaster recovery

Best Practices:

  • Regularly audit your policy list to ensure it's up-to-date
  • Use descriptive names that clearly indicate each policy's purpose
  • Document policy rationale in the description field
  • Group related policies using blueprints for easier management
  • Remove obsolete policies to reduce configuration complexity
  • Use consistent naming conventions across policy types
  • Track policy updates to maintain change history
  • Test policy configurations in non-production environments first
  • Maintain documentation of policy settings outside the platform
  • Review policies when regulations or requirements change

Security Considerations:

  • Policy configurations may contain sensitive rules or thresholds
  • Access to policy list should be restricted to authorized personnel
  • Changes to policies can significantly impact agent behavior
  • Document all policy modifications for audit trails
  • Test policy changes thoroughly before production deployment

Fetching a Policy

Retrieve detailed information about a specific policy by its ID. This endpoint provides complete access to all policy configuration details, including the type, configuration settings, associated resources, and metadata. Use this when you need to inspect or verify a policy's current settings.

GET /api/v1/policy/{policyId}/fetch
Authorization: Bearer YOUR_API_TOKEN

http

Response Format:

{
  "id": "policy_abc123",
  "name": "30DayRetention",
  "description": "Automatically archive conversations older than 30 days",
  "type": "retention",
  "blueprintId": "blueprint_xyz789",
  "config": {},
  "meta": {},
  "createdAt": "2025-11-10T08:00:00Z",
  "updatedAt": "2025-11-15T14:30:00Z"
}

json

Response Fields:

  • id: Unique identifier for the policy
  • name: Descriptive name of the policy
  • description: Detailed explanation of what the policy does
  • type: Policy type (currently only "retention" is available)
  • blueprintId: Associated blueprint ID (if applicable)
  • config: Policy-specific configuration object
  • meta: Additional metadata
  • createdAt: Timestamp when the policy was created
  • updatedAt: Timestamp of last policy modification

Understanding Policy Configuration:

The config field contains type-specific settings that control how the policy operates. The structure varies depending on the policy type. Currently, only retention policies are supported.

Common Use Cases:

  • Configuration Review: Verify current policy settings before making changes
  • Audit Compliance: Document policy configurations for regulatory requirements
  • Troubleshooting: Inspect policy details when investigating unexpected behavior
  • Migration: Export policy settings for backup or environment migration
  • Documentation: Generate reports of current policy configurations

Best Practices:

  • Fetch policy details before updating to ensure you have current values
  • Regularly review policy configurations to ensure they align with requirements
  • Document any manual changes to policy settings for audit trails
  • Verify policy effectiveness by reviewing associated resource states

Updating a Policy

Modify an existing policy's configuration, settings, or metadata. This endpoint allows you to update any aspect of a policy including its name, description, type-specific configuration, and resource associations. Changes take effect immediately and will be applied to future policy evaluations.

POST /api/v1/policy/{policyId}/update
Content-Type: application/json

{
  "name": "60DayRetention",
  "description": "Extended retention period for compliance requirements",
  "type": "retention",
  "config": {}
}

http

Updatable Fields:

  • name: Update the policy's descriptive name
  • description: Modify the detailed explanation
  • type: Change the policy type (currently only "retention" is available)
  • config: Update type-specific configuration settings
  • blueprintId: Change blueprint association
  • meta: Update additional metadata

Important Considerations:

  • Policy changes affect future evaluations only, not past actions
  • Changing critical configuration may have immediate impact on data management
  • The policy type can be modified, but currently only "retention" is supported
  • Configuration updates should be tested carefully before production deployment
  • Policy execution continues without interruption during updates

Update Strategies:

Incremental Updates: Include only the fields you want to change. Omitted fields retain their current values. This is the recommended approach for targeted modifications.

Complete Replacement: Provide all fields to replace the entire policy configuration. This ensures a known configuration state but requires fetching current values first.

Configuration Validation: The platform validates configuration structure before applying updates. Invalid configurations will be rejected with detailed error messages to help you correct issues before affecting policy operation.

Common Use Cases:

  • Adjust Retention Periods: Modify retention settings based on changing requirements
  • Update Descriptions: Clarify policy purposes as organizational needs evolve
  • Change Associations: Move policies between blueprints for better organization
  • Refine Configuration: Optimize policy settings based on operational experience
  • Compliance Updates: Adjust policies to meet new regulatory requirements

Best Practices:

  • Fetch current policy configuration before updating to avoid overwriting recent changes
  • Test configuration changes in non-production environments first
  • Document why policy changes were made for audit and compliance purposes
  • Monitor policy execution after updates to verify expected behavior
  • Consider the impact on existing data before changing retention settings
  • Update policy descriptions to reflect any significant configuration changes

Deleting a Policy

Permanently remove a policy from your account. This endpoint completely deletes the policy and all its configuration. Once deleted, the policy will no longer be evaluated or executed, and its automated operations will cease immediately. This action cannot be undone.

POST /api/v1/policy/{policyId}/delete
Content-Type: application/json

{}

http

Important Considerations:

  • Policy deletion is immediate and irreversible
  • All automated operations governed by this policy will stop
  • Historical data affected by the policy remains in its current state
  • Deletion does not undo previous policy actions (e.g., archived/deleted data)
  • Associated resources (conversations, messages, etc.) are not affected
  • Only the policy configuration itself is removed

Impact on Data Management:

When you delete a retention policy, for example:

  • Data already archived remains archived
  • Data already deleted remains deleted
  • Future retention operations will not occur
  • No automatic cleanup of data covered by the deleted policy

When to Delete Policies:

  • Obsolete Rules: Policy requirements have changed and rule is no longer needed
  • Replaced Configuration: A new policy supersedes the old one
  • Testing Cleanup: Removing test or temporary policies from development
  • Organizational Changes: Business processes no longer require the policy
  • Compliance Updates: Regulatory requirements have changed

Alternatives to Deletion:

Before deleting a policy, consider these alternatives:

  • Update: Modify the policy configuration to meet current needs instead
  • Disable: Some organizations prefer to disable rather than delete for audit trails
  • Archive: Export policy configuration before deletion for historical records
  • Document: Record the reason for deletion for compliance purposes

Best Practices:

  • Verify the policy ID before deletion to avoid removing the wrong policy
  • Document why the policy is being deleted for audit and compliance records
  • Review what data or operations were governed by the policy before deletion
  • Consider exporting policy configuration for backup before deleting
  • Notify relevant stakeholders before deleting policies that affect shared resources
  • Verify no critical automated operations depend on the policy before deletion
  • After deletion, update any documentation that referenced the removed policy

Recovery:

Deleted policies cannot be recovered. If you need the same policy later, you must recreate it with the same configuration. Keep backups of critical policy configurations if there's any chance you might need them again.

Go to cbk.ai