Portals

Portals are scoped access surfaces for ChatBotKit capabilities. From an API perspective, a portal is a resource that binds:

• an identity (id, slug, optional name/description)
• optional resource linkage (blueprintId)
• runtime behavior (config)
• optional metadata (meta)

Use portals when you need controlled, isolated entry points for different audiences while keeping one backend account and data plane.

Typical developer scenarios include:

• creating dedicated support or operations endpoints
• exposing different app sets per team/environment
• enforcing domain/email based access rules
• customizing layout/branding per deployment target

This manual focuses on the config object and endpoint semantics used by portal create/update APIs. Treat it as the implementation reference for programmatic portal provisioning.

Portal Resource Lifecycle

1. Create a portal with name, slug, and optional config.
2. Fetch/list to inspect current configuration/state.
3. Update with the next full desired config object.
4. Delete when the access surface is no longer needed.

Portal Config Model

The portal config object has three top-level sections:

• apps: app slug to app-specific config object
• users: email matcher to access object
• layout: optional UI configuration

Minimal example:

App Configuration

Common app slugs used in portals:

• chat
• task
• connect
• inbox
• usage

If an app slug is present in config.apps, it is exposed in that portal.

Chat

The chat app config commonly supports bot exposure, starter prompts, and labeling fields.

Inbox

Inbox filters can be configured to control sidebar filter visibility.

User Access Matchers

config.users supports exact emails and wildcard domains.

Layout Configuration

config.layout supports high-level UI behavior and branding.

Update Semantics

On portal update, config is treated as a full object replacement. Send the complete desired config object when calling update to avoid unintentionally dropping existing values.

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.

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.

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.

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.

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.