ChatBotCustomDomain Model

class smarter.apps.chatbot.models.ChatBotCustomDomain(*args, **kwargs)[source]

Bases: MetaDataWithOwnershipModel

Represents a DNS host record for a customer account’s ChatBot, linked to an AWS Hosted Zone.

This model is used to manage custom domains for chatbots within the Smarter platform. Each instance of this model corresponds to a DNS host (subdomain) that is associated with a specific customer account and is managed through AWS Route 53 Hosted Zones.

The primary purpose of this model is to enable customers to use their own branded domains for chatbot endpoints, rather than relying solely on default platform-provided domains. This allows for improved branding, trust, and integration with customer infrastructure.

Key Features

  • Associates a custom domain with a customer Account.

  • Stores the AWS Hosted Zone ID for DNS management and automation.

  • Tracks the verification status of the domain, indicating whether DNS records have been correctly configured and validated.

  • Supports caching of verified domains for efficient lookup and validation across the platform.

Usage Scenarios

  • When a customer wishes to deploy a chatbot at a custom subdomain (e.g., chatbot.example.com), an instance of this model is created to represent and manage that domain.

  • The platform uses the AWS Hosted Zone ID to automate DNS record creation and validation as part of the chatbot deployment workflow.

  • The is_verified field is updated as part of the DNS verification process, ensuring that only properly configured domains are used for chatbot endpoints.

Integration

  • This model is referenced by other chatbot-related models, such as ChatBot and ChatBotCustomDomainDNS, to provide a complete mapping between chatbots, their domains, and DNS records.

  • The platform uses this model to enforce domain uniqueness and to prevent conflicts between customer accounts.

Notes

  • The domain name must be a valid DNS hostname and is validated upon saving.

  • Caching is used to optimize the retrieval of verified domains, reducing database load and improving performance for domain-related checks.

  • This model is intended for internal use within the Smarter platform and is not exposed directly to end users.

Example

# Create a new custom domain for a chatbot
custom_domain = ChatBotCustomDomain.objects.create(
    account=my_account,
    aws_hosted_zone_id="Z1234567890ABCDEF",
    domain_name="chatbot.example.com",
    is_verified=False,
)

# Retrieve all verified custom domains
verified_domains = ChatBotCustomDomain.get_verified_domains()
Parameters:

  • id (BigAutoField) – Primary key: ID

  • created_at (DateTimeField) – Created at

  • updated_at (DateTimeField) – Updated at

  • name (CharField) –

    Name. Name in camelCase, e.g., ‘apiKey’, no special characters.

    The name of the function available to the ChatBot. Example: “weather”

  • description (TextField) – Description. A brief description of this resource. Be verbose, but not too verbose.

  • version (CharField) – Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.

  • annotations (JSONField) – Annotations. Key-value pairs for annotating this resource.

  • aws_hosted_zone_id (CharField) –

    Aws hosted zone id

    The AWS Hosted Zone ID associated with this custom domain. This ID is used for DNS management via AWS Route 53. Example: “Z1234567890ABCDEF”

  • domain_name (CharField) –

    Domain name

    The custom domain name for the ChatBot. This should be a valid DNS hostname. Example: “chatbot.example.com”

  • is_verified (BooleanField) –

    Is verified

    Indicates whether the custom domain has been verified. A verified domain has the correct DNS records configured. This is managed by the asynchronous ChatBot deployment process. Example: True

Relationship fields:

Parameters:

  • user_profile (ForeignKey to UserProfile) – User profile (related name: chatbotcustomdomains)

  • tags (TaggableManager to Tag) – Tags. Tags for categorizing and organizing this resource. (related name: chatbotcustomdomain)

  • tagged_items (GenericRelation to TaggedItem) – Tagged items (related name: +)

Reverse relationships:

Parameters:

  • chatbotcustomdomaindns (Reverse ForeignKey from ChatBotCustomDomainDNS) – All ChatBot Custom Domain DNS of this chat bot custom domain (related name of custom_domain)

  • chatbot (Reverse ForeignKey from ChatBot) –

    All ChatBots of this chat bot custom domain (related name of custom_domain)

    The ChatBot instance associated with this function. Example: ChatBot(id=1, name=”my-chatbot”)

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

annotations

JSONField

Annotations. Key-value pairs for annotating this resource.

Type:

Type

aws_hosted_zone_id

CharField

Aws hosted zone id

The AWS Hosted Zone ID associated with this custom domain. This ID is used for DNS management via AWS Route 53. Example: “Z1234567890ABCDEF”

Type:

Type

chatbot_set

Reverse ForeignKey from ChatBot

All ChatBots of this chat bot custom domain (related name of custom_domain)

Type:

Type

chatbotcustomdomaindns_set

Reverse ForeignKey from ChatBotCustomDomainDNS

All ChatBot Custom Domain DNS of this chat bot custom domain (related name of custom_domain)

Type:

Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created. This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:

Type

description

TextField

Description. A brief description of this resource. Be verbose, but not too verbose.

Type:

Type

domain_name

CharField

Domain name

The custom domain name for the ChatBot. This should be a valid DNS hostname. Example: “chatbot.example.com”

Type:

Type

classmethod get_verified_domains()[source]

Get all verified custom domains from cache or database.

Returns:

List of verified domain names.

Return type:

List[str]

id

BigAutoField

Primary key: ID

Type:

Type

is_verified

BooleanField

Is verified

Indicates whether the custom domain has been verified. A verified domain has the correct DNS records configured. This is managed by the asynchronous ChatBot deployment process. Example: True

Type:

Type

name

CharField

Name. Name in camelCase, e.g., ‘apiKey’, no special characters.

Type:

Type

objects = <django.db.models.Manager object>
save(*args, **kwargs)[source]

Save the ChatBotCustomDomain instance, validating the domain name.

Raises:

ValidationError – If the domain name is not valid.

Returns:

None

tagged_items

Reverse GenericRelation from ChatBotCustomDomain

All + of this tagged item (related name of tagged_items)

Type:

Type

tags = <taggit.managers._TaggableManager object>
updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated. This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:

Type

user_profile

ForeignKey to UserProfile

User profile (related name: chatbotcustomdomains)

Type:

Type

user_profile_id

Internal field, use user_profile instead.

version

CharField

Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.

Type:

Type