Skip to main content

Developer Guide

This page describes the data model for Account and Profile, the most relevant fields and relationships, and how Profiles are resolved during ingestion. Use this as a reference when building integrations, migrations, or ingestion adapters.

Data model overview​

At a high level, an Account owns many Profile records. Feature flags and configs can live at the Account level (tenant‑wide) and be overridden per Profile.

Notes and constraints:

  • Identifiers
    • Account.code and Profile.code are globally unique slugs used widely in integrations and URLs.
      • Account codes: lowercase alphanumeric only (^[a-z0-9]+$), min length 3.
      • Profile codes: lowercase alphanumeric plus dash (^[a-z0-9-]+$), min length 3.
  • Config/versioning
    • Profile.active_config points at the currently active ProfileConfig version that determines which data belongs to the profile. Multiple config versions can co‑exist (e.g., training a new model while the current stays active).
    • Profile.platform overrides the account‑wide active_platform_config for platform integrations when needed.
  • Models/ML
    • active_url_model, active_url_model_b, and active_gpt_model reference deployed dashboard.MLModel versions used by various features.
    • Guardrails for URL model deployment are enforced via url_model_ratio_threshold, min_num_unique_urls, and min_conversation_coverage.
  • Assistants
    • New fields use *_assistant_new and M2M collections (on_conversation_*_assistants). Earlier single‑FK fields are marked deprecated but may exist for legacy flows.
  • Internationalization
    • Live translation can be enabled at both Account and Profile levels; Profile settings govern per‑profile behavior when enabled.

Field references (selected)​

  • Account

    • Anonymization: agent_pseudonyms, anonymizer_model, anonymize_messages, anonymize_messages_ignore_urls, anonymize_messages_ignorelist.
    • Compliance / tenancy: is_trial, is_uat, data_retention_period, inactive_user_deactivation_period_days, uuid.
    • Platform and ML: active_platform_config, active_w2v_model, ner_custom_entities.
    • Feature flags: deploy_knowledge_assist, entity_clipboard, rule_engine, trigger_engine, live_translation_enabled, passwordless_login.

  • Profile

    • Identity: account, code, name, description.
    • Feature flags: custom_messages, sticky_messages, assisted_intake, recommendation_engine, search, recommend_text_suggestions, autocomplete_with_text_suggestions, image_search, entities_command, gpt.
    • Config: ui_config, experimental_config, active_config, platform.
    • Models: active_url_model, active_url_model_b, active_gpt_model, url_model_ratio_threshold, min_num_unique_urls, min_conversation_coverage.
    • Assistants: knowledge_assistant_new, summarizer_assistant_new, on_demand_assistants, on_conversation_*_assistants (deprecated single‑FK fields retained for legacy flows).

Profile assignment during ingestion​

Deepdesk assigns a Profile using a simple precedence:

  • If an explicit profile_code is provided, use it.
  • Otherwise, try to match a Profile from available metadata using the profile matcher.
  • If neither is available on a message, inherit the conversation’s current profile_code.

This applies during conversation creation/updates and for each ingested message. The diagrams below illustrate the flow.

Conversation creation/update​

Message ingestion​

Implementation notes and guardrails:

  • Idempotency: Use stable external IDs at the conversation/message level; the service checks conversation.has_message(message) and skips already‑known messages.
  • Validation: Account.code and Profile.code are globally unique; avoid cross‑account assumptions based on profile alone.
  • Observability: Consider emitting metrics for metadata‑based matches, explicit profile code usage, and exclusion events.
  • Security: Do not infer Account from Profile alone on external input; resolve account context first (routing/auth).

Development tips​

  • Prefer referencing profiles by code in integrations; avoid database IDs across services.
  • When introducing new per‑profile features, add fields to Profile or embed under ui_config/experimental_config behind a feature flag.
  • Keep deprecated assistant fields only as long as migrations require; prefer the M2M collections going forward.