Widget Configuration

Verificações opcionais de exemplos

• Verificar um snippet do Widget. Verifique o código colado com base no Scenario ID fornecido. Isso não acessa o seu site.

Em um navegador compatível, essas verificações também ficam disponíveis como ferramentas do site. Os links abrem os formulários habituais.

Widget Configuration

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.

Get Widget Configuration

Escopo: read_all

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

Shell

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

Python

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,
  "attachments_active": true,
  "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" },
    "transparency": { "style": "none", "opacity": 70 }
  }
}

Conteúdo & Mensagens

Field	Description
welcome_message string	Mensagem de boas-vindas principal exibida quando o widget abre (HTML). Painel: Canais > Seu site > Conteúdo de texto > Mensagem de boas-vindas
welcome_message2 string	Mensagem de boas-vindas secundária exibida abaixo da saudação principal. Disponível pela API; não há campo de edição para ela no painel.
header string	Texto exibido na barra de cabeçalho do widget. Painel: Canais > Seu site > Conteúdo de texto > Texto do cabeçalho
subtitle string	Texto de subtítulo exibido abaixo do cabeçalho. Disponível pela API; não há campo de edição para ele no painel.
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", "bottom-middle" 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	Personalização do tema. colors (header, accent, bolha de mensagem, texto da IA, link, input, border e mais, como hex ou rgb()/rgba()) se aplicam apenas quando theme é "custom"; radius ("sm"/"base"/"lg"/"full" para bolhas, input e botões), font.size ("sm"/"base"/"lg") e transparency se aplicam em todos os modos de tema. transparency.style é "none" (sólido, o padrão) ou "glass" (translúcido, com a página atrás desfocada); transparency.opacity (40–95, padrão 70) é a tonalidade do Vidro em porcentagem, e o widget nunca a exibe mais fraca do que o texto do tema precisa sobre qualquer site (50 em Claro, 65 em Escuro, calculado a partir das cores em Personalizado). Se em Personalizado nenhuma opacidade mantiver o texto legível, o widget é exibido sólido e o transparency.style salvo continua "glass". A Chat Page é sempre exibida sólida. No PATCH, envie o objeto inteiro: chaves ausentes voltam aos padrões, então um objeto antigo sem transparency volta a "none". widget_theme_custom e cada uma de suas seções (colors, radius, font, transparency) devem ser objetos; null assume os padrões do tema inteiro ou dessa seção e qualquer outro valor é rejeitado com 422. 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
attachments_active boolean	Permitir que os visitantes anexem uma imagem ou um documento. A predefinição é true. Quando é false, o botão de Anexos de ficheiros fica oculto e os carregamentos são rejeitados
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)

Update Widget Configuration

Escopo: 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.

Nota

Para avatar_image, envie os dados da imagem codificados em base64 (máx. 5 MB). A resposta retorna a URL da imagem armazenada. Enviar avatar_image: null exclui o avatar (o widget então não exibe nenhum avatar), e enviar use_default_avatar: true restaura o AI Agent Avatar padrão.

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

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
}'

Python

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).

---