Portals

Portals are specialized interfaces that allow you to create controlled access points to your ChatBotKit resources. Each portal provides a unique endpoint where external users can interact with your bots, datasets, and other resources without requiring direct access to your main account.

Portals are particularly useful for agencies managing multiple clients, businesses offering white-label solutions, or organizations that need to provide isolated access to specific resources while maintaining centralized control and configuration.

Creating Portals

Creating a portal establishes a new access point with its own unique identifier and configuration. The portal's slug serves as the primary identifier and becomes part of the access URL, allowing you to create memorable, branded endpoints for your users.

To create a portal, you must provide a unique slug that will identify the portal within its domain. The slug must be URL-friendly and cannot conflict with existing portals in the same domain. You can also optionally associate the portal with a blueprint to inherit resource configurations and provide custom configuration through the config object.

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

{
  "name": "Agency Client Portal",
  "description": "Custom portal for client access",
  "slug": "acme-corp",
  "blueprintId": "blueprint_abc123",
  "config": {
    "theme": "light",
    "branding": {
      "logo": "https://example.com/logo.png"
    }
  }
}

http

The slug you choose becomes part of the portal's access URL and must be unique within the specified domain (defaults to CHATBOTKIT_AGENCY). The config object allows you to customize the portal's appearance, behavior, and available features according to your specific requirements.

Important: Portal slugs cannot be changed after creation. Choose a slug that reflects the portal's purpose and is easy to remember. If you need to change a slug, you must create a new portal with the desired slug and migrate any existing configurations.

Deleting Portals

Deleting a portal permanently removes the access point and all its configuration, making it no longer accessible to users. This operation is irreversible and should be performed carefully, particularly if the portal is actively being used or referenced in external systems.

When you delete a portal, the deletion is immediate and complete. The portal's slug becomes available for reuse, and any configuration or metadata associated with the portal is permanently removed. However, the underlying resources (bots, datasets, blueprints) that the portal provided access to remain intact and are not affected by the deletion.

POST /api/v1/portal/{portalId}/delete
Content-Type: application/json

{}

http

Replace {portalId} with either the portal's unique identifier (ID) or its slug. The request body must be an empty object, as portal deletion requires no additional parameters beyond identification and authentication.

Important Considerations Before Deletion:

  • Verify that no users are currently accessing the portal
  • Update any documentation or integrations that reference the portal URL
  • Consider exporting portal configuration if you may need to recreate it
  • Ensure any dependent systems are prepared for the portal's removal
  • Check if the portal is referenced in any automation or workflow systems

What Gets Deleted: The portal deletion removes:

  • The portal record and all its metadata
  • All configuration settings stored in the portal
  • The portal's slug reservation in its domain

What Remains Unchanged: Portal deletion does NOT affect:

  • Associated blueprints (they remain fully functional)
  • Bots, datasets, or other resources the portal accessed
  • Other portals or their configurations
  • User accounts or permissions

Recovery: Once deleted, a portal cannot be recovered. If you need the same functionality, you must create a new portal with the same configuration. The slug will be available for reuse immediately after deletion.

Fetching a Portal

Retrieving detailed information about a specific portal allows you to inspect its current configuration, verify its settings, and obtain the data needed for management operations or display in administrative interfaces.

The fetch operation returns complete portal information including all configuration details, associated blueprint references, metadata, and timestamps. This is particularly useful when you need to verify portal settings before making updates or when building management interfaces that display portal details to administrators.

GET /api/v1/portal/{portalId}/fetch
Content-Type: application/json

http

Replace {portalId} with either the portal's unique identifier (ID) or its slug. The platform supports both forms of identification, making it convenient to fetch portals using whichever identifier you have available in your application context.

Response Structure: The returned portal object includes all properties set during creation and any subsequent updates, including:

  • Basic information: name, description
  • Portal identifiers: id, slug, domain
  • Resource associations: blueprintId (if configured)
  • Configuration: config object with all portal settings
  • Metadata: meta object with custom properties
  • Timestamps: createdAt, updatedAt

Common Use Cases:

  • Displaying portal details in administrative dashboards
  • Verifying portal configuration before updates
  • Auditing portal settings and access patterns
  • Building portal management interfaces
  • Troubleshooting portal-related issues

Updating Portals

Updating a portal allows you to modify its configuration, appearance, and resource associations without disrupting existing access. This flexibility enables you to refine portal settings over time as requirements evolve, update branding elements, or adjust which resources are accessible through the portal.

Portal updates support modifying most properties including the name, description, blueprint association, slug, and configuration object. You can update individual properties or multiple properties in a single request, and only the properties you specify will be modified while others remain unchanged.

POST /api/v1/portal/{portalId}/update
Content-Type: application/json

{
  "name": "Updated Portal Name",
  "description": "New description reflecting updated purpose",
  "config": {
    "theme": "dark",
    "branding": {
      "logo": "https://example.com/new-logo.png",
      "primaryColor": "#4F46E5"
    }
  }
}

http

Slug Updates: While you can update the slug property, be cautious when doing so as it changes the portal's access URL. Any existing links or integrations using the old slug will need to be updated. Consider the impact on users and systems that may be accessing the portal through its URL before changing the slug.

Blueprint Changes: Updating the blueprintId allows you to change which blueprint (if any) the portal is associated with. This can affect which resources are accessible through the portal and what configurations are inherited. Set blueprintId to null to remove the blueprint association entirely.

Configuration Merging: The config object is replaced entirely with each update - it is not merged with the existing configuration. If you want to preserve existing configuration values while adding new ones, you must include all desired configuration in the update request.

Metadata Updates: The meta property supports partial updates, meaning you can update specific metadata fields without affecting others. This is useful for maintaining custom properties like tags, categories, or integration identifiers without having to resend the entire metadata object.

Listing Portals

Retrieving a list of your portals allows you to manage and monitor all access points you've created. The list endpoint supports pagination and filtering capabilities, enabling you to efficiently work with large numbers of portals and locate specific configurations quickly.

The list operation returns all portals owned by the authenticated user, including their configuration details, associated blueprints, and metadata. This comprehensive view helps you understand your portal ecosystem and identify which resources are accessible through each portal.

GET /api/v1/portal/list
Content-Type: application/json

http

The response includes an array of portal objects, each containing the portal's identifier, slug, configuration, and timestamps. You can use pagination parameters to control the number of results returned and navigate through large portal collections efficiently.

Pagination Parameters:

  • cursor: Pagination cursor for retrieving the next page of results
  • order: Sort order for results (asc or desc, defaults to desc)
  • take: Number of items to retrieve per page

Metadata Filtering: The list endpoint supports filtering based on metadata properties. You can use the meta query parameter to filter portals by custom metadata fields you've set during creation or updates. This is particularly useful for organizing portals by client, project, or environment.

Performance Considerations: When working with many portals, use pagination to avoid performance issues. The default ordering by creation date (descending) ensures you see your most recent portals first, which is typically the most common access pattern.

Go to cbk.ai