---
title: "Update chatbot settings"
method: POST
path: "/update-chatbot-settings"
tags: ["Chatbot Operations"]
---

# Update chatbot settings

`POST /update-chatbot-settings`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/update-chatbot-settings`
- Auth: HTTP bearer

This API endpoint allows you to edit your chatbot. Only the fields you send are changed; fields set to `null` are ignored.

## Request body

- UpdateChatbotSettingReq
  - `chatbotId` string, required: The unique identifier allocated to the chatbot.
  - `chatbotName` string: The new name of the chatbot.
  - `basePrompt` string: The base prompt (instructions) for the chatbot.
  - `initialMessages` string[]: Array of initial messages the chatbot shows when a conversation starts.
  - `suggestedMessages` string[]: Array of suggested messages shown in the chatbot.
  - `visibility` 'private' | 'public': The visibility of the chatbot. It controls whether your chatbot is accessible to others.
  - `onlyAllowOnAddedDomains` boolean: Whether the chatbot can be embedded (iframe or widget) on other websites; `false` disables embedding. Allowed domains are set by `domains`.
  - `domains` string[]: The domains on which the iframe and widget are allowed. Replaces the current list.
  - `disallowedUrls` string[]: Pages on which the chat widget is not shown. Replaces the current list.
  - `rateLimitPoints` number: The maximum number of messages one device can send every `rateLimitTimeframe` seconds. Each message counts as one here, however many message credits its model consumes.
  - `rateLimitTimeframe` number: The time window, in seconds, to which the `rateLimitPoints` message limit applies.
  - `rateLimitMessage` string: The error message shown to the user when the conversation is rate limited.
  - `baseModel` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4.1-nano' | 'gpt-4.1-mini' | 'gpt-4.1' | 'gpt-5-nano' | 'gpt-5-mini' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6-luna' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-nano' | 'gpt-5.4-mini' | 'gpt-o1' | 'gpt-o3-mini' | 'gpt-o3' | 'gpt-o4-mini' | 'claude-4-5-sonnet' | 'claude-4-6-sonnet' | 'claude-4-5-haiku' | 'claude-4-opus' | 'claude-4.1-opus' | 'claude-4.5-opus' | 'claude-4.6-opus' | 'claude-5-opus' | 'claude-5-sonnet' | 'claude-5-5-opus' | 'claude-5-5-sonnet' | 'claude-5-5-haiku' | 'gemini-3.0-flash' | 'gemini-3.1-flash' | 'gemini-3.5-flash-lite' | 'gemini-3.7-flash' | 'gemini-2.5-pro' | 'gemini-3.0-pro' | 'gemini-3.1-pro' | 'deepseek-r1' | 'deepseek-v3.2' | 'mancer-deepseek-v4-flash': The large language model (OpenAI GPT, Anthropic Claude, Google Gemini or DeepSeek) used in our RAG processing pipeline. In a HIPAA workspace, models not covered by a BAA are rejected.
  - `temperature` number: The temperature of the AI model, in the range [0, 1].
  - `storeChat` boolean: Indicates whether chat history is stored on our server. All chatbot models, including medical-chat-human and medical-chat-vet, start with storage enabled by default. Storage can be disabled for any model.
  - `qALinks` FaqLink[]: Links to frequently asked questions pages shown in the chatbot. Replaces the current links; items without both `text` and `link` are dropped.
    - `text` string: The descriptive text for the link.
    - `link` string: The URL that users are taken to when they click the link.
  - `showCalendar` boolean: Specifies whether the Calendly booking button should be displayed in the chatbot widget or iframe.
  - `calendarUrl` string: The Calendly URL where users can schedule appointments.
  - `calendarMessage` string: The message to display for appointment scheduling.
  - `calCom` object: The Cal.com booking button settings. The object replaces the current settings as a whole.
    - `showCalendar` boolean: Whether the Cal.com booking button is displayed.
    - `username` string: The Cal.com username (or username/event path) to book with.
    - `calendarMessage` string: The label of the booking button.
    - `hideEventTypeDetails` boolean: Whether the event type details are hidden in the booking view.
    - `brandColor` string: The brand color of the booking view.
    - `layout` string: The layout of the booking view (for example `month`).
  - `enableBouncingAnimation` boolean: Whether the chat bubble bounces at the start of a session to attract attention.
  - `enableBubbleSound` boolean: Whether a sound plays when the initial-message bubble pops up.
  - `bubbleSize` number: The size of the chat bubble button, in pixels. Values that are not positive numbers are ignored.
  - `inputPlaceholderMsg` string: The placeholder text of the message input.
  - `rerank` boolean: Whether retrieved knowledge base chunks are reranked before the chatbot answers. Reranking costs extra message credits.
  - `sources` object: Whether and how the sources used for an answer are shown under it.
    - `enable` boolean: Whether sources are shown.
    - `label` string: The label shown above the sources.
  - `footer` string: Text shown at the bottom of the chat widget.
  - `ignoreDataSource` boolean: Whether your uploaded data should be ignored when the chatbot responds. If set to true, the chatbot answers like a general-purpose AI chatbot without your knowledge base. This option applies to chatbots based on the `custom-data-upload` model.
  - `leadsConfig` ChatbotLeadsConfig: The information to be collected from potential customers.
    - `message` string: The message shown at the top of the customer information form.
    - `collectName` boolean: Whether the form asks for the customer's name.
    - `collectEmail` boolean: Whether the form asks for the customer's email address.
    - `collectPhone` boolean: Whether the form asks for the customer's phone number.
    - `nameMessage` string: The label of the name field. You can translate it into your own language.
    - `emailMessage` string: The label of the email field. You can translate it into your own language.
    - `phoneMessage` string: The label of the phone field. You can translate it into your own language.
  - `styles` ChatbotStyles: The appearance settings of the chat widget.
    - `theme` 'light' | 'dark': The theme of the chatbot interface.
    - `buttonColor` string: The color of the chat bubble button in RGB format (e.g. rgb(0, 0, 0)).
    - `displayName` string: The display name of the chatbot. In responses, only returned when one is set.
    - `alignChatButton` 'left' | 'right': The alignment of the chat bubble button.
    - `userMessageColor` string: The background color of the user's messages in RGB format (e.g. rgb(59, 129, 246)).
    - `actionButtonColor` string: The color of the action buttons in RGB format (e.g. rgb(59, 129, 246)).
    - `profilePictureFile` string: URL or path of the chatbot's profile picture. Only returned when one is set.
    - `bubblePictureFile` string: URL or path of the chat bubble icon. Only returned when one is set.
    - `autoOpenChatWindowAfter` number: The time (in seconds) after which the chat window opens automatically. A negative value disables automatic opening.

## Response `200`

Successful response.

- SuccessStatus
  - `status` 'success', required

## Other responses

- `400`: The settings could not be saved. For example: `chatbotId` is missing, `visibility`, `baseModel` or `temperature` has an invalid value, `basePrompt` is empty or not a string, the base model is not allowed in a HIPAA workspace, or a value was rejected when saving.
- `401`: Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which.
- `403`: The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace.
- `409`: Only when the request includes `baseModel`: the workspace is being reconfigured. Retry the request.
- `429`: The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)