Skip to main content
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

​
current_user
User
The message coming from the UI.

​
ChatProfile Fields

FieldTypeRequiredDescription
namestrYesInternal identifier. Stored in user_session as "chat_profile".
markdown_descriptionstrYesDescription shown in the profile selector, supports Markdown.
iconstrNoURL of the profile icon.
display_namestrNoUser-facing label shown in the UI. Falls back to name if omitted.
starterslist[Starter]NoStarter messages shown when this profile is selected.
config_overridesChainlitConfigOverridesNoPer-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},
                    )
                ),
            ),
        ),