Implementing Custom Actions (Buttons)

For a complete overview of the interactivity system, please read the Actions guide.

This guide focuses on Custom Actions, which allow you to go beyond the built-in behaviors and trigger your application’s unique functions directly from the C1 UI. This makes the generative interface a true, interactive part of your application, enabling powerful workflows such as:

Downloading a generated report.
Opening a product-specific checkout modal.
Triggering a function in your application, like creating a new project or sending an email.

Implementing a Custom Action

Let’s walk through an example of implementing a download_report custom action. It involves two steps: defining the action on your backend and handling it on your frontend.

1. Define the Custom Action (Backend)

To make the LLM aware of your custom action, you must define its name and the parameters it accepts. This is done by passing a c1_custom_actions object within the metadata of your API call. We recommend using a schema library (like Zod for TypeScript or Pydantic for Python) to define your action’s parameters.

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/embed",
  apiKey: process.env.THESYS_API_KEY,
});

const messages = [
  { role: "system", content: "When the user asks to download data, offer them a 'download_report' button." },
  { role: "user", content: "Can I get a copy of our quarterly sales data?" }
];

const response = await client.chat.completions.create({
  model: "c1/anthropic/claude-sonnet-4/v-20250930",
  messages: messages,
  metadata: {
    thesys: JSON.stringify({
      c1_custom_actions: {
        download_report: zodToJsonSchema(z.object({
          reportType: z.enum(["sales", "marketing", "inventory"]).describe("The category of the report."),
          format: z.enum(["csv", "pdf"]).default("pdf").describe("The file format for the download."),
          quarter: z.string().optional().describe("The specific quarter for the report, e.g., 'Q3 2025'."),
        })),
      }
    }),
  },
});

import os
import json, jsonref
import openai
from pydantic import BaseModel, Field
from typing import Literal, Optional

client = openai.OpenAI(
    api_key=os.environ.get("THESYS_API_KEY"),
    base_url="https://api.thesys.dev/v1/embed",
)

# Define the parameters for the custom action using Pydantic
class DownloadReportParams(BaseModel):
    reportType: Literal["sales", "marketing", "inventory"] = Field(..., description="The category of the report.")
    format: Literal["csv", "pdf"] = Field(default="pdf", description="The file format for the download.")
    quarter: Optional[str] = Field(default=None, description="The specific quarter for the report, e.g., 'Q3 2025'.")


messages = [
    {"role": "system", "content": "When the user asks to download data, offer them a 'download_report' button."},
    {"role": "user", "content": "Can I get a copy of our quarterly sales data?"}
]

def generate_schema(model: BaseModel):
  schema = model.model_json_schema()
  schema = jsonref.replace_refs(schema, proxies=False) # dereference $refs and $defs
  schema.pop("$defs", None) # remove $defs
  schema.pop("$ref", None) # remove $refs
  return schema

# Construct the metadata payload
thesys_metadata = {
    "c1_custom_actions": {
        "download_report": generate_schema(DownloadReportParams)
    }
}

response = client.chat.completions.create(
    model="c1/anthropic/claude-sonnet-4/v-20250930",
    messages=messages,
    metadata={"thesys": json.dumps(thesys_metadata)},
)

When the LLM generates a UI that includes a “Download Report” button, it will attach the action type download_report and the corresponding parameters to it.

2. Handle the Custom Action (Frontend)

On the frontend, you use the same onAction callback from the core Actions guide. You simply add a new case to your switch statement to handle your custom action type. Using <C1Component> Your handler should check for the download_report action type and then trigger your application’s logic, like opening a modal or starting a file download.

<C1Component
  c1Response={c1Response}
  isStreaming={isLoading}
  onAction={(event) => {
    switch (event.type) {
      // Your custom action case
      case "download_report":
        // Optionally add a message to the UI to confirm the action
        pushUserMessageToChat(`Downloading ${event.params.reportType} report...`);
        // Trigger your application's download logic with the action's parameters
        downloadReport(event.params);
        break;

      // Built-in action cases
      case "open_url":
        window.open(event.params.url, "_blank", "noopener,noreferrer");
        break;

      case "continue_conversation":
      default:
        const { llmFriendlyMessage, humanFriendlyMessage } = event.params;
        pushUserMessageToChat(humanFriendlyMessage);
        callApi(llmFriendlyMessage);
        break;
    }
  }}
/>

Using <C1Chat>

If you are using persistence with the useThreadManager hook, you need to pass the onAction callback directly to the hook.

The <C1Chat> component handles built-in actions automatically, so its onAction prop is used exclusively for your custom actions.

<C1Chat
  apiUrl="/api/chat"
  onAction={(event) => {
    // C1Chat handles 'continue_conversation' and 'open_url',
    // so you only need to handle your custom actions.
    switch (event.type) {
      case "download_report":
        // Trigger your application's logic
        downloadReport(event.params);
        break;
    }
  }}
/>

import { useThreadManager, C1Chat } from "@thesysai/genui-sdk";

const threadManager = useThreadManager(
  apiUrl="/api/chat",
  onAction={(event) => {
    switch (event.type) {
      case "download_report":
        // Trigger your application's logic
        downloadReport(event.params);
        break;
    }
  }}
);
<C1Chat
  threadManager={threadManager}
/>

Getting Started

Basics

Interactivity

Styling

Conversational UI

Artifacts

Advanced

Ecosystem

Implementing Custom Actions (Buttons)

Implementing a Custom Action

1. Define the Custom Action (Backend)

2. Handle the Custom Action (Frontend)

​Implementing a Custom Action

​1. Define the Custom Action (Backend)

​2. Handle the Custom Action (Frontend)

Implementing a Custom Action

1. Define the Custom Action (Backend)

2. Handle the Custom Action (Frontend)