Chat Profiles

Decorator to define the list of chat profiles. If authentication is enabled, you can access the user details to create the list of chat profiles conditionally. The icon is optional.

Parameters

User

The message coming from the UI.

ChatProfile Fields

Field	Type	Required	Description
`name`	`str`	Yes	Internal identifier. Stored in `user_session` as `"chat_profile"`.
`markdown_description`	`str`	Yes	Description shown in the profile selector, supports Markdown.
`icon`	`str`	No	URL of the profile icon.
`display_name`	`str`	No	User-facing label shown in the UI. Falls back to `name` if omitted.
`starters`	`list[Starter]`	No	Starter messages shown when this profile is selected.
`config_overrides`	`ChainlitConfigOverrides`	No	Per-profile config overrides.

Usage

Simple example

import chainlit as cl


@cl.set_chat_profiles
async def chat_profile():
    return [
        cl.ChatProfile(
            name="GPT-3.5",
            markdown_description="The underlying LLM model is **GPT-3.5**.",
            icon="https://picsum.photos/200",
        ),
        cl.ChatProfile(
            name="GPT-4",
            markdown_description="The underlying LLM model is **GPT-4**.",
            icon="https://picsum.photos/250",
        ),
    ]

@cl.on_chat_start
async def on_chat_start():
    chat_profile = cl.user_session.get("chat_profile")
    await cl.Message(
        content=f"starting chat using the {chat_profile} chat profile"
    ).send()

With authentication

from typing import Optional

import chainlit as cl


@cl.set_chat_profiles
async def chat_profile(current_user: cl.User):
    if current_user.metadata["role"] != "ADMIN":
        return None

    return [
        cl.ChatProfile(
            name="GPT-3.5",
            markdown_description="The underlying LLM model is **GPT-3.5**, a *175B parameter model* trained on 410GB of text data.",
        ),
        cl.ChatProfile(
            name="GPT-4",
            markdown_description="The underlying LLM model is **GPT-4**, a *1.5T parameter model* trained on 3.5TB of text data.",
            icon="https://picsum.photos/250",
        ),
        cl.ChatProfile(
            name="GPT-5",
            markdown_description="The underlying LLM model is **GPT-5**.",
            icon="https://picsum.photos/200",
        ),
    ]


@cl.password_auth_callback
def auth_callback(username: str, password: str) -> Optional[cl.User]:
    if (username, password) == ("admin", "admin"):
        return cl.User(identifier="admin", metadata={"role": "ADMIN"})
    else:
        return None


@cl.on_chat_start
async def on_chat_start():
    user = cl.user_session.get("user")
    chat_profile = cl.user_session.get("chat_profile")
    await cl.Message(
        content=f"starting chat with {user.identifier} using the {chat_profile} chat profile"
    ).send()

With Localization

The @cl.set_chat_profiles callback accepts an optional language parameter, allowing you to return localized chat profile labels and descriptions.

With localization

import chainlit as cl


@cl.set_chat_profiles
async def chat_profile(current_user: cl.User, language: str):
    if language == "fr":
        return [
            cl.ChatProfile(
                name="GPT-4",
                markdown_description="Le modèle sous-jacent est **GPT-4**.",
                icon="https://picsum.photos/250",
            ),
        ]
    return [
        cl.ChatProfile(
            name="GPT-4",
            markdown_description="The underlying LLM model is **GPT-4**.",
            icon="https://picsum.photos/250",
        ),
    ]

Display Name

Use display_name to show a user-friendly label in the UI while keeping a stable internal identifier in name. This is useful for localised names or names containing special characters.

import chainlit as cl

@cl.set_chat_profiles
async def chat_profile():
    return [
        cl.ChatProfile(
            name="ad_designer",          # internal ID stored in user_session
            display_name="广告设计师",    # shown in the UI
            markdown_description="Profile for ad design tasks.",
        ),
        cl.ChatProfile(
            name="copywriter",
            display_name="Copywriter",
            markdown_description="Profile for writing tasks.",
        ),
    ]

@cl.on_chat_start
async def on_chat_start():
    # user_session always holds the internal `name`, not display_name
    chat_profile = cl.user_session.get("chat_profile")  # "ad_designer"

Since version 2.8.5.

Dynamic Configuration

You can override the global config.toml for specific ChatProfiles by configuring overrides

from chainlit.config import (
    ChainlitConfigOverrides,
    FeaturesSettings,
    McpFeature,
    UISettings,
)

@cl.set_chat_profiles
async def chat_profile(current_user: cl.User):
    return [
        cl.ChatProfile(
            name="MCP Enabled",
            markdown_description="Profile with **MCP features enabled**. This profile has *Model Context Protocol* support activated. [Learn more](https://example.com/mcp)",
            icon="https://picsum.photos/250",
            starters=starters,
            config_overrides=ChainlitConfigOverrides(
                ui=UISettings(name="MCP UI"),
                features=FeaturesSettings(
                    mcp=McpFeature(
                        enabled=True,
                        stdio={"enabled": True},
                        sse={"enabled": True},
                        streamable_http={"enabled": True},
                    )
                ),
            ),
        ),

Life Cycle Hooks

Chat

Elements

Ask User

Integrations

Misceallaneous

Input Widgets

Parameters

ChatProfile Fields

Usage

With Localization

Display Name

Dynamic Configuration

​Parameters

​ChatProfile Fields

​Usage

​With Localization

​Display Name

​Dynamic Configuration

Parameters

ChatProfile Fields

Usage

With Localization

Display Name

Dynamic Configuration