Widget Configuration

Leia e atualize a configuração do widget do site via API.

O widget é uma interface de chat que você incorpora no seu site — ele aparece como uma bolha flutuante no canto da página, na qual os visitantes podem clicar para abrir uma conversa com seu Agente de IA. O widget é totalmente personalizável: você controla suas cores, tamanho, posição, mensagens de saudação e comportamento.

Essas configurações também afetam o embed, que é uma versão em página inteira ou inline da mesma interface de chat e que você pode posicionar diretamente no layout da sua página (em vez da bolha flutuante). Tanto o widget quanto o embed compartilham a mesma configuração de aparência, mensagens e comportamento.

Com esses endpoints, você pode personalizar de forma programática como o Quickchat AI aparece no seu site — combinar as cores da sua marca, configurar formulários de pré-chat para coletar informações dos visitantes, configurar indicadores de digitação, habilitar entrada por voz e muito mais. Para instruções de configuração, consulte o guia do canal Website.

Scope: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell
Python

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"],
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "launcher_label": "Ask AI",
  "launcher_draggable": false,
  "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "theme": "light",
  "widget_theme_custom": {
    "colors": {
      "background": "#ffffff",
      "header": "#ffffff",
      "header_text": "#030712",
      "accent": "#27272a",
      "accent_hover": "#374151",
      "accent_text": "#ffffff",
      "bubble": "#27272a",
      "bubble_text": "#ffffff",
      "ai_bubble_text": "#030712",
      "tertiary": "#afafb2",
      "link": null,
      "input_background": "#ffffff",
      "input_text": "#030712",
      "input_placeholder": "#9ca3af",
      "border": "#e5e7eb",
      "sidebar": {
        "background": "#f5f5f5",
        "text": null,
        "accent": "#e5e5e5",
        "accent_text": null
      }
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" }
  }
}

Conteúdo & Mensagens

Field	Description
`welcome_message` string	Mensagem de boas-vindas principal exibida quando o widget abre (HTML). Dashboard: Website > Greeting
`welcome_message2` string	Mensagem de boas-vindas secundária exibida abaixo da saudação principal
`header` string	Texto exibido na barra de cabeçalho do widget. Dashboard: Website > Header
`subtitle` string	Texto de subtítulo exibido abaixo do cabeçalho. Dashboard: Website > Subtitle
`input_placeholder` string	Texto de placeholder no campo de entrada de mensagem (ex.: “Type your message…”)
`conversation_starters` array of strings or null	Sugestões de abertura exibidas como botões clicáveis quando o widget abre. Até 3 entradas, cada uma com até ~100 caracteres
`background_disclaimer_text` string or null	Texto de aviso exibido na parte inferior da janela de chat

Aparência

Field	Description
`primary_color` string	Cor de destaque do widget como valor CSS rgb (ex.: `"rgb(0, 122, 255)"`). Usada para botões, links e bolhas de mensagem do usuário
`header_color` string	Cor de fundo do cabeçalho como valor CSS rgb
`header_text_color` boolean	Brilho do texto do cabeçalho. `true` = texto branco/claro (para cabeçalhos escuros), `false` = texto escuro (para cabeçalhos claros). Nota: apesar do nome, isto é um boolean, não uma string de cor
`size` string	Preset de tamanho do launcher: `"small"`, `"medium"` ou `"large"` (mostrados no dashboard como Small, Input Only e Classic)
`location` string	Posição do widget na página: `"top-left"`, `"top-right"`, `"bottom-left"` ou `"bottom-right"`
`launcher_label` string or null	Texto no botão launcher small (`size: "small"`), máx. 25 caracteres. `null` usa o padrão (`"Ask AI"`); `""` exibe um launcher somente com ícone
`launcher_draggable` boolean	Permite que os visitantes arrastem o launcher para outra posição na página
`window_height` integer	Altura do widget em pixels (400-1200)
`window_width` integer	Largura do widget em pixels (300-700)
`avatar_image` string or null	URL do AI Agent Avatar, exibido tanto no cabeçalho do chat quanto como ícone da bolha flutuante. Faça upload via PATCH em base64. `null` significa que o avatar foi excluído e o widget não exibe nenhum avatar
`bubble_icon_image` string or null	Deprecated. Sempre espelha `avatar_image` — o ícone da bolha e o avatar do chat agora são uma única imagem (veja Unificação do AI Agent Avatar)
`default_avatar_image` string	Somente leitura. URL do AI Agent Avatar padrão que `use_default_avatar` restaura
`theme` string	Modo de tema de cores: `"light"` ou `"dark"` (presets fixos) ou `"custom"` (aplica a paleta `widget_theme_custom`)
`widget_theme_custom` object	Paleta personalizada aplicada quando `theme` é `"custom"`. Contém `colors` (header, accent, bolha de mensagem, texto da IA, `link`, input, border e mais, como hex ou `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` para bolhas, input e botões) e `font.size` (`"sm"`/`"base"`/`"lg"`). No PATCH, envie o objeto inteiro — chaves ausentes voltam aos padrões. `colors.link` tem padrão `null`, o que significa que os links herdam a cor do texto ao redor. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) tematiza apenas a sidebar da Chat Page autônoma (ignorada pelas visualizações de bolha e embed); seus `text` e `accent_text` têm padrão `null`, o que significa que uma cor legível é derivada automaticamente do fundo correspondente

Comportamento

Field	Description
`popup_active` boolean	Exibir um popup perto da bolha do widget para incentivar os visitantes a iniciar uma conversa
`window_auto_open` boolean	Abrir o widget automaticamente quando a página carrega (em vez de exibir apenas a bolha)
`header_collapse` boolean	Permitir que os visitantes recolham a área do cabeçalho para ter mais espaço de chat
`typing` boolean	Exibir uma animação de indicador de digitação enquanto a IA gera uma resposta
`streaming_active` boolean	Transmitir as respostas da IA palavra por palavra em vez de exibir a mensagem completa de uma vez
`voice_active` boolean	Habilitar entrada por voz — os visitantes podem enviar mensagens usando o microfone
`link_tracking_active` boolean	Rastrear quando os visitantes clicam em links nas respostas da IA. Os cliques rastreados aparecem como eventos `tracked_link` em Conversation Events
`white_label` boolean	Remover a marca “Powered by Quickchat” do widget

Formulário de Pré-chat

Field	Description
`prechat_active` boolean	Habilitar o formulário de pré-chat. Quando ativo, os visitantes precisam preencher o formulário antes de conversar
`prechat_header_text` string or null	Texto do cabeçalho do formulário de pré-chat
`prechat_button_text` string or null	Rótulo do botão de envio no formulário de pré-chat
`prechat_message_text` string or null	Texto/instruções do corpo exibidos no formulário de pré-chat (HTML)

Scope: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Request Body — Todos os campos são opcionais. Inclua apenas os campos que você quer atualizar.

Unificação do AI Agent Avatar

O avatar do chat (logo do cabeçalho) e o ícone da bolha flutuante (launcher) foram unificados em uma única imagem, o AI Agent Avatar, armazenado em avatar_image. O ícone da bolha sempre o espelha — não existe mais uma imagem de launcher independente. Se você integra diretamente com este endpoint, observe as seguintes mudanças de comportamento:

O upload via bubble_icon_image está deprecated: ele agora define o AI Agent Avatar unificado, que também substitui a imagem exibida no cabeçalho do chat. Use avatar_image em vez disso.
bubble_icon_image: null é um no-op. Ele costumava limpar o ícone do launcher; como o launcher espelha o avatar, exclua via avatar_image: null em vez disso.
Agentes que nunca personalizaram seu avatar exibem o AI Agent Avatar padrão (veja default_avatar_image na resposta) tanto no cabeçalho quanto no launcher.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Response 200 OK — Retorna a configuração do widget atualizada (mesmo schema da resposta de Get Widget Configuration).

Widget Configuration