> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="current_user" type="User">
  The message coming from the UI.
</ParamField>

## 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

```python Simple example theme={null}
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()
```

```python With authentication theme={null}
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.

```python With localization theme={null}
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.

```python theme={null}
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"
```

<Note>
  Since version **2.8.5**.
</Note>

## Dynamic Configuration

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

```python theme={null}
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},
                    )
                ),
            ),
        ),
```