# Update chatbot settings

`POST https://api.chat-data.com/api/v2/update-chatbot-settings`

Canonical: https://www.chat-data.com/api-reference/update-chatbot-settings

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

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

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The unique identifier allocated to the chatbot. |
| chatbotName | string | no | The new name of the chatbot. |
| basePrompt | string | no | The base prompt (instructions) for the chatbot. |
| initialMessages | array of string | no | Array of initial messages the chatbot shows when a conversation starts. |
| suggestedMessages | array of string | no | Array of suggested messages shown in the chatbot. |
| visibility | string | no | The visibility of the chatbot. It controls whether your chatbot is accessible to others. One of: `private`, `public`. |
| onlyAllowOnAddedDomains | boolean | no | Whether the chatbot can be embedded (iframe or widget) on other websites; `false` disables embedding. Allowed domains are set by `domains`. |
| domains | array of string | no | The domains on which the iframe and widget are allowed. Replaces the current list. |
| disallowedUrls | array of string | no | Pages on which the chat widget is not shown. Replaces the current list. |
| rateLimitPoints | number | no | 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 | no | The time window, in seconds, to which the `rateLimitPoints` message limit applies. |
| rateLimitMessage | string | no | The error message shown to the user when the conversation is rate limited. |
| baseModel | string | no | 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. One of: `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`. |
| temperature | number | no | The temperature of the AI model, in the range [0, 1]. |
| storeChat | boolean | no | 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 | array of object | no | Links to frequently asked questions pages shown in the chatbot. Replaces the current links; items without both `text` and `link` are dropped. |
| qALinks[].text | string | no | The descriptive text for the link. |
| qALinks[].link | string | no | The URL that users are taken to when they click the link. |
| showCalendar | boolean | no | Specifies whether the Calendly booking button should be displayed in the chatbot widget or iframe. |
| calendarUrl | string | no | The Calendly URL where users can schedule appointments. |
| calendarMessage | string | no | The message to display for appointment scheduling. |
| calCom | object | no | The Cal.com booking button settings. The object replaces the current settings as a whole. |
| calCom.showCalendar | boolean | no | Whether the Cal.com booking button is displayed. |
| calCom.username | string | no | The Cal.com username (or username/event path) to book with. |
| calCom.calendarMessage | string | no | The label of the booking button. |
| calCom.hideEventTypeDetails | boolean | no | Whether the event type details are hidden in the booking view. |
| calCom.brandColor | string | no | The brand color of the booking view. |
| calCom.layout | string | no | The layout of the booking view (for example `month`). |
| enableBouncingAnimation | boolean | no | Whether the chat bubble bounces at the start of a session to attract attention. |
| enableBubbleSound | boolean | no | Whether a sound plays when the initial-message bubble pops up. |
| bubbleSize | number | no | The size of the chat bubble button, in pixels. Values that are not positive numbers are ignored. |
| inputPlaceholderMsg | string | no | The placeholder text of the message input. |
| rerank | boolean | no | Whether retrieved knowledge base chunks are reranked before the chatbot answers. Reranking costs extra message credits. |
| sources | object | no | Whether and how the sources used for an answer are shown under it. |
| sources.enable | boolean | no | Whether sources are shown. |
| sources.label | string | no | The label shown above the sources. |
| footer | string | no | Text shown at the bottom of the chat widget. |
| ignoreDataSource | boolean | no | 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 | object | no | The information to be collected from potential customers. |
| leadsConfig.message | string | no | The message shown at the top of the customer information form. |
| leadsConfig.collectName | boolean | no | Whether the form asks for the customer's name. |
| leadsConfig.collectEmail | boolean | no | Whether the form asks for the customer's email address. |
| leadsConfig.collectPhone | boolean | no | Whether the form asks for the customer's phone number. |
| leadsConfig.nameMessage | string | no | The label of the name field. You can translate it into your own language. |
| leadsConfig.emailMessage | string | no | The label of the email field. You can translate it into your own language. |
| leadsConfig.phoneMessage | string | no | The label of the phone field. You can translate it into your own language. |
| styles | object | no | The appearance settings of the chat widget. |
| styles.theme | string | no | The theme of the chatbot interface. One of: `light`, `dark`. |
| styles.buttonColor | string | no | The color of the chat bubble button in RGB format (e.g. rgb(0, 0, 0)). |
| styles.displayName | string | no | The display name of the chatbot. In responses, only returned when one is set. |
| styles.alignChatButton | string | no | The alignment of the chat bubble button. One of: `left`, `right`. |
| styles.userMessageColor | string | no | The background color of the user's messages in RGB format (e.g. rgb(59, 129, 246)). |
| styles.actionButtonColor | string | no | The color of the action buttons in RGB format (e.g. rgb(59, 129, 246)). |
| styles.profilePictureFile | string | no | URL or path of the chatbot's profile picture. Only returned when one is set. |
| styles.bubblePictureFile | string | no | URL or path of the chat bubble icon. Only returned when one is set. |
| styles.autoOpenChatWindowAfter | number | no | The time (in seconds) after which the chat window opens automatically. A negative value disables automatic opening. |

Send only the fields you want to set; optional fields you omit are left unchanged.

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/update-chatbot-settings' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05"
}'
```

## Example response (200)

```json
{
  "status": "success"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 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. |