ChatInterface

Build chatbot UIs quickly with Gradio’s specialized ChatInterface class

ChatInterface is Gradio’s high-level abstraction specifically designed for creating chatbot UIs. It provides a simple way to wrap chat functions and automatically handles message history, user interactions, and streaming responses.

What is ChatInterface?

ChatInterface is similar to Interface but specialized for conversational AI applications. It automatically provides:

• A chat display with message history
• An input textbox (or multimodal input)
• Submit, retry, undo, and clear buttons
• Example prompts
• Streaming support for real-time responses

Basic usage

The simplest chatbot requires just a function that takes a message and history:

import gradio as gr

def echo(message, history):
    return message

demo = gr.ChatInterface(fn=echo)
demo.launch()

Your function receives:

• message: The user’s current message (string)
• history: List of previous messages in OpenAI format

And should return:

• A string response, or
• A Gradio component (like an image), or
• A complete message dict

Message history format

The history parameter is a list of OpenAI-style message dictionaries:

[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi! How can I help?"},
    {"role": "user", "content": "What's the weather?"}
]

You can use this history to maintain context across multiple turns:

import gradio as gr
import random

def chatbot(message, history):
    # Access previous messages
    if len(history) > 0:
        prev_msg = history[-1]["content"]
        return f"You just said: {prev_msg}. Now you're saying: {message}"
    return f"First message: {message}"

demo = gr.ChatInterface(fn=chatbot)
demo.launch()

Streaming responses

For real-time streaming, make your function a generator:

import gradio as gr
import time

def slow_echo(message, history):
    response = ""
    for char in message:
        response += char
        time.sleep(0.05)
        yield response

demo = gr.ChatInterface(fn=slow_echo)
demo.launch()

ChatInterface automatically detects generator functions and displays responses as they stream.

Multimodal chat

Enable file uploads with multimodal=True:

import gradio as gr

def multimodal_chat(message, history):
    # message is now a dict with "text" and "files" keys
    text = message["text"]
    files = message.get("files", [])
    
    response = f"You said: {text}"
    if files:
        response += f"\nYou uploaded {len(files)} file(s)"
    return response

demo = gr.ChatInterface(
    fn=multimodal_chat,
    multimodal=True
)
demo.launch()

When multimodal=True, the input message becomes a dictionary:

{
    "text": "Check out this image",
    "files": ["path/to/uploaded/file.jpg"]
}

Examples

Provide example prompts to help users get started:

import gradio as gr

demo = gr.ChatInterface(
    fn=chatbot,
    examples=[
        {"text": "Hello!"},
        {"text": "How are you?"},
        {"text": "Tell me a joke"}
    ],
    example_labels=["Greeting", "Question", "Fun"],
    example_icons=["👋", "❓", "😄"]
)

For multimodal examples, include files:

demo = gr.ChatInterface(
    fn=multimodal_chat,
    multimodal=True,
    examples=[
        {"text": "Describe this image", "files": ["example.jpg"]},
        {"text": "What's in this photo?", "files": ["photo.png"]}
    ]
)

Additional inputs

Add configuration parameters that appear in a collapsible section:

import gradio as gr

def chatbot(message, history, temperature, max_tokens):
    # Use temperature and max_tokens in your logic
    return f"Processing with temp={temperature}, max_tokens={max_tokens}"

demo = gr.ChatInterface(
    fn=chatbot,
    additional_inputs=[
        gr.Slider(0, 2, value=0.7, label="Temperature"),
        gr.Slider(1, 2048, value=512, label="Max Tokens")
    ],
    additional_inputs_accordion="Model Parameters"
)

Additional input values are passed as extra arguments to your function after message and history.

Additional outputs

Display extra information alongside the chat:

import gradio as gr

def chatbot_with_metadata(message, history):
    response = f"Echo: {message}"
    metadata = {"message_length": len(message), "timestamp": "2024-01-01"}
    return response, metadata

with gr.Blocks() as demo:
    gr.ChatInterface(
        fn=chatbot_with_metadata,
        additional_outputs=[gr.JSON(label="Metadata")]
    )

demo.launch()

Customization options

Title and description

demo = gr.ChatInterface(
    fn=chatbot,
    title="My Custom Chatbot",
    description="This chatbot echoes your messages back to you."
)

Custom chatbot component

Provide your own configured Chatbot component:

import gradio as gr

custom_chatbot = gr.Chatbot(
    height=600,
    bubble_full_width=False,
    avatar_images=("user.png", "bot.png")
)

demo = gr.ChatInterface(
    fn=chatbot,
    chatbot=custom_chatbot
)

Custom textbox

Customize the input textbox:

import gradio as gr

custom_textbox = gr.Textbox(
    placeholder="Type your message here...",
    lines=3
)

demo = gr.ChatInterface(
    fn=chatbot,
    textbox=custom_textbox
)

Button labels

demo = gr.ChatInterface(
    fn=chatbot,
    submit_btn="Send Message",
    stop_btn="Stop Generation",
    clear_btn=None  # Hide the clear button
)

Editable messages

Allow users to edit their previous messages:

import gradio as gr

demo = gr.ChatInterface(
    fn=chatbot,
    editable=True  # Users can click to edit past messages
)

Retry and undo

ChatInterface automatically provides retry and undo buttons:

• Retry: Regenerates the last assistant response
• Undo: Removes the last user message and assistant response

These are built-in and require no additional code.

Flagging and feedback

Enable users to flag messages or provide feedback:

import gradio as gr

demo = gr.ChatInterface(
    fn=chatbot,
    flagging_mode="manual",  # "manual" or "never"
    flagging_options=["Like", "Dislike"],
    flagging_dir="./flagged_chats"
)

Like/Dislike options appear as thumbs up/down icons next to messages.

Caching examples

Cache example responses for instant loading:

import gradio as gr

demo = gr.ChatInterface(
    fn=slow_chatbot,
    examples=[{"text": "Hello"}, {"text": "How are you?"}],
    cache_examples=True,  # Pre-compute responses
    cache_mode="eager"  # "eager" or "lazy"
)

API configuration

Control API endpoint visibility:

demo = gr.ChatInterface(
    fn=chatbot,
    api_name="chat",  # Custom endpoint name
    api_description="Chat with the bot",
    api_visibility="public"  # "public", "private", or "undocumented"
)

Advanced: Returning components

Return Gradio components directly from your function:

import gradio as gr
from PIL import Image

def multimodal_bot(message, history):
    if "image" in message.lower():
        # Return an Image component
        img = Image.new('RGB', (300, 300), color='blue')
        return gr.Image(value=img)
    else:
        return "I can only show images!"

demo = gr.ChatInterface(fn=multimodal_bot)

Performance options

import gradio as gr

demo = gr.ChatInterface(
    fn=chatbot,
    concurrency_limit=5,  # Max simultaneous users
    show_progress="minimal",  # "full", "minimal", or "hidden"
    autoscroll=True,  # Auto-scroll to new messages
    autofocus=True  # Focus input on load
)

Complete example

Here’s a fully-featured chatbot:

import gradio as gr
import random
import time

def chatbot(message, history, temperature):
    responses = [
        "That's interesting!",
        "Tell me more.",
        "I understand.",
        "How does that make you feel?"
    ]
    
    response = random.choice(responses)
    
    # Stream the response
    for i in range(len(response)):
        time.sleep(0.05)
        yield response[:i+1]

demo = gr.ChatInterface(
    fn=chatbot,
    title="Friendly Chatbot",
    description="A simple conversational AI",
    examples=[
        {"text": "Hello!"},
        {"text": "What's the weather like?"}
    ],
    additional_inputs=[
        gr.Slider(0, 1, value=0.7, label="Temperature")
    ],
    flagging_mode="manual",
    flagging_options=["Like", "Dislike"],
    cache_examples=True
)

demo.launch()

See also

• Interface - General-purpose interface builder
• Blocks - For more complex layouts
• Chatbot Component - The underlying chat display component
• Events - Event system reference