Personalização da interface do widget

Q: Qual é a diferença entre cabeçalho colorido e minimalista?

Colorido usa sua cor primária (ou header-bg) como plano de fundo do cabeçalho com texto branco. Minimalista usa um plano de fundo branco com texto escuro e uma borda sutil — um visual mais limpo e moderno. Ao usar o estilo minimalista, o atributo data-header-bg é ignorado.

Personalize seu widget de chat Toda a personalização do widget é feita por meio de atributos data-* na tag de script de incorporação. Não são necessárias alterações de CSS ou JavaScript — o widget usa um Shadow DOM que isola seus estilos do seu site.

Como funciona a personalização

O Widget Externo da REDA AI é renderizado dentro de um Shadow DOM, o que significa que o CSS do seu site não consegue alcançar o interior do widget, e os estilos do widget não conseguem afetar sua página. Toda a personalização é feita adicionando atributos data-* à tag <script> de incorporação.

Classes CSS não funcionam

Como o widget usa um Shadow DOM, adicionar regras CSS que visam nomes de classe do widget na folha de estilos do seu site não terá efeito nenhum. Use os atributos data-* listados abaixo.

Configurações da Definição de Agente

Algumas configurações de aparência vêm do registro de Definição de Agente no Salesforce, não do código de incorporação:

Configuração	Onde configurar	Descrição
Welcome Message	Definição de Agente → Mensagem de boas-vindas externa	A primeira mensagem que os visitantes veem ao abrir o chat
Imagem do mascote	Definição de Agente → Imagem do mascote	Avatar personalizado exibido no balão, no hero de boas-vindas e ao lado das mensagens
Nome do agente	Definição de Agente → Nome de exibição	Exibido no cabeçalho e usado no título do hero de boas-vindas
Saudação proativa	Definição de Agente → Iniciar ao carregar	Desativado por padrão. Quando ativado, o painel envia uma saudação assim que é montado em uma página de registro, de modo que o agente começa com percepções sobre aquele registro em vez de esperar ser perguntado.

Atributos obrigatórios

Atributo	Descrição
`data-api-key`	Sua Chave de API Externa da REDA AI
`data-endpoint`	A URL do endpoint da API de chat da REDA AI

Estilo do balão

O balão é o botão flutuante em que os visitantes clicam para abrir o chat. Você pode exibi-lo como um círculo (padrão) ou como um botão em formato de pílula com um rótulo de texto.

Atributo	Valores	Padrão	Descrição
`data-bubble-style`	`circle` \| `pill`	`circle`	Formato do botão flutuante
`data-bubble-label`	Qualquer texto	(nenhum)	Texto do rótulo exibido na pílula (por exemplo, “Ask Support”). Obrigatório para o estilo pílula.
`data-bubble-size`	Número (px)	`60`	Diâmetro do balão circular (ignorado para o estilo pílula)

Exemplo de balão em pílula

data-bubble-style="pill"
data-bubble-label="Ask REDA AI"

Exibe um botão em pílula arredondado com um ícone e o texto “Ask REDA AI”. Se uma imagem de mascote estiver configurada na Definição de Agente, ela substitui o ícone padrão na pílula.

Estilo do cabeçalho

O cabeçalho aparece na parte superior do painel de chat. Escolha entre um cabeçalho colorido (plano de fundo na cor da marca) ou um cabeçalho minimalista (plano de fundo branco e limpo).

Atributo	Valores	Padrão	Descrição
`data-header-style`	`colored` \| `minimal`	`colored`	Estilo do plano de fundo do cabeçalho
`data-header-bg`	Cor hexadecimal	Igual à cor primária	Cor de fundo do cabeçalho (aplica-se apenas ao estilo `colored`)

Exemplo de cabeçalho minimalista

data-header-style="minimal"

Renderiza um cabeçalho branco e limpo, com texto escuro e uma borda inferior sutil. O atributo data-header-bg é ignorado ao usar o estilo minimalista.

Hero de boas-vindas

O hero de boas-vindas é uma seção de marca exibida no painel de chat. Ele exibe um avatar ou ícone, um título grande e um subtexto opcional — criando uma primeira impressão acolhedora.

Atributo	Valores	Padrão	Descrição
`data-show-welcome-hero`	`true` \| `false`	`true`	Mostrar ou ocultar a seção do hero de boas-vindas
`data-welcome-heading`	Qualquer texto	“Como o [Agent Name] pode ajudar?”	Título do hero. Use `{title}` como espaço reservado para o nome do agente.
`data-welcome-subtext`	Qualquer texto	(nenhum)	Subtexto opcional abaixo do título

Exemplo de hero de boas-vindas

data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your properties"

O espaço reservado {title} é substituído pelo nome do agente e renderizado na cor da sua marca. Se uma imagem de mascote estiver configurada, ela aparece como um avatar circular acima do título.

Cores

Atributo	Padrão	Descrição
`data-primary-color`	`#0176D3`	Cor primária da marca — usada no balão, no cabeçalho (estilo colorido), nas mensagens do usuário e em elementos de destaque
`data-header-bg`	Igual à cor primária	Plano de fundo do cabeçalho (apenas estilo colorido)
`data-user-msg-bg`	Igual à cor primária	Plano de fundo do balão de mensagem do usuário
`data-user-msg-text-color`	`#ffffff`	Cor do texto dentro dos balões de mensagem do usuário
`data-bg-color`	Padrão do tema	Cor de fundo do painel
`data-bg-secondary-color`	Padrão do tema	Plano de fundo do balão de mensagem do assistente e do indicador de digitação
`data-text-color`	Padrão do tema	Cor principal do texto
`data-border-color`	Padrão do tema	Cor das bordas e divisores

Exemplo de cores de marca personalizadas

data-primary-color="#1B5E20"
data-user-msg-bg="#2E7D32"
data-bg-color="#FAFAFA"

Define um esquema de cores verde: balão e cabeçalho verdes, mensagens do usuário em um verde ligeiramente mais escuro e um plano de fundo do painel cinza-claro.

Layout e posição

Atributo	Valores / Tipo	Padrão	Descrição
`data-display-mode`	`bubble` \| `docked-right` \| `docked-left`	`bubble`	Como o painel se abre — um cartão flutuante, ou um painel de altura total encaixado na borda direita ou esquerda. Veja Modo de exibição abaixo.
`data-position`	`bottom-right` \| `bottom-left`	`bottom-right`	Em qual canto o balão aparece. Independente do Modo de exibição — você pode manter o balão no canto inferior esquerdo e mesmo assim encaixar o painel à direita.
`data-panel-width`	Número (px)	`400`	Largura do painel de chat. Apenas no modo balão — ignorado quando encaixado.
`data-panel-height`	Número (px)	`550`	Altura do painel de chat. Apenas no modo balão — um painel encaixado é sempre de altura total.
`data-dock-width`	Número (px), ou qualquer largura CSS (`30vw`)	Adapta-se à tela	Largura do painel encaixado. Apenas nos modos encaixados. Omita-o e o painel se ajusta sozinho à tela (aproximadamente um terço da janela, dentro de limites razoáveis).
`data-border-radius`	Número (px)	`12`	Raio dos cantos do painel e do balão
`data-z-index`	Número	`999999`	z-index CSS do widget (aumente se outros elementos se sobrepuserem)
`data-title`	Texto	`AI Assistant`	Título do painel do widget exibido no cabeçalho

Modo de exibição

Modo de exibição controla como o painel de chat se abre. O balão de lançamento está sempre presente em todos os modos — os visitantes clicam nele para abrir o assistente, e o Modo de exibição decide o que eles obtêm.

Modo	O que o visitante vê	Melhor para
`bubble` (padrão)	Um cartão de chat flutuante que abre logo acima do balão, deixando a maior parte da página visível.	Sites de marketing e conteúdo, onde a página é o foco principal e o chat é um auxílio.
`docked-right`	Um painel de altura total que desliza a partir da borda direita e permanece ao lado da página.	Conversas mais longas, comparação de opções, ou leitura de resultados enquanto navega.
`docked-left`	O mesmo painel de altura total, encaixado na borda esquerda.	Sites cujo próprio conteúdo ou controles ficam à direita.

Um painel encaixado dá ao assistente muito mais espaço — útil quando as respostas incluem cartões de imóveis, fotos ou comparações que ficam apertadas no cartão flutuante.

data-display-mode="docked-right"
data-dock-width="420"

O balão nunca desaparece. O Modo de exibição só muda como o painel se abre — o balão de lançamento é exibido nos três modos, e data-position continua decidindo em qual canto ele fica. Se você omitir data-display-mode por completo, o widget se comporta exatamente como antes, então as incorporações já existentes não precisam de alterações.

Dimensionamento: largura do painel vs. largura do encaixe. data-panel-width e data-panel-height dimensionam o cartão flutuante e são ignorados quando encaixado. data-dock-width dimensiona o painel encaixado e é ignorado no modo balão. Se uma configuração de tamanho parecer não ter efeito, verifique se você está definindo a que corresponde ao seu Modo de exibição. Omita data-dock-width e o painel se ajusta sozinho à tela do visitante.

Em celulares. Todos os modos abrem em tela cheia em celulares, então um painel encaixado não precisa de tratamento móvel especial. Veja Comportamento em dispositivos móveis para alterar isso.

Também no portal da Community. Os mesmos três modos estão disponíveis para o widget da Community — escolha Modo de exibição (Bubble, Docked Right, Docked Left) no componente REDA AI no Experience Builder. Não é necessário código de incorporação.

Tema

Atributo	Valores	Padrão	Descrição
`data-theme`	`light` \| `dark`	`light`	Tema de cores do widget. O modo escuro usa planos de fundo escuros com texto claro.

Tipografia

Atributo	Tipo	Padrão	Descrição
`data-font-family`	Stack de fontes CSS	Stack de fontes do sistema	Família de fontes personalizada (por exemplo, `'Poppins', sans-serif`). A fonte deve estar carregada na sua página.
`data-font-size`	Número (px)	`14`	Tamanho base da fonte para mensagens e campo de entrada

Comportamento em dispositivos móveis

Atributo	Valores / Tipo	Padrão	Descrição
`data-mobile-breakpoint`	Número (px)	`640`	Largura de tela abaixo da qual o comportamento móvel é ativado
`data-mobile-fullscreen`	`true` \| `false`	`true`	Quando ativado, o painel de chat se expande para tela cheia em dispositivos móveis

Comportamento

Atributo	Valores / Tipo	Padrão	Descrição
`data-open-on-load`	`true` \| `false`	`false`	Abre automaticamente o painel de chat quando a página carrega
`data-enable-voice`	`true` \| `false`	`true`	Exibe o botão de voz (microfone) para que os visitantes possam ditar mensagens. Defina como `false` para ocultá-lo. O botão só aparece em navegadores que suportam entrada de voz. Veja Entrada de Voz.
`data-typing-speed`	Número	`25`	Palavras por segundo da animação de digitação ao revelar as respostas
`data-cache-ttl-minutes`	Número (mín. 1)	`5`	Com que frequência o cache do script do widget é atualizado (em minutos)

Texto e internacionalização (i18n)

Todo o texto voltado ao usuário no widget pode ser substituído para fins de marca ou tradução:

Atributo	Padrão	Descrição
`data-input-placeholder`	Type a message...	Texto de espaço reservado do campo de entrada
`data-aria-open`	Open chat	Rótulo ARIA para o balão quando o chat está fechado
`data-aria-close`	Close chat	Rótulo ARIA para o balão quando o chat está aberto
`data-aria-send`	Send message	Rótulo ARIA para o botão de enviar
`data-aria-typing`	Assistant is typing	Rótulo ARIA para o indicador de digitação
`data-error-rate-limited`	Please wait a moment before sending again.	Mensagem de erro de limite de taxa
`data-error-max-messages`	This conversation has reached its limit. Please start a new one.	Erro de limite máximo de mensagens atingido
`data-error-session-expired`	Session expired. Reconnecting...	Mensagem de expiração de sessão
`data-error-generic`	Something went wrong. Please try again.	Mensagem de erro genérica
`data-error-connect`	Unable to connect. Please refresh and try again.	Mensagem de falha de conexão

Exemplos completos

Incorporação mínima (todos os padrões)

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>

Usa todos os padrões: balão circular, cabeçalho colorido, hero de boas-vindas, tema claro, posição inferior direita.

Balão em pílula moderno com cabeçalho minimalista

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-bubble-style="pill"
  data-bubble-label="Ask REDA AI"
  data-header-style="minimal"
  data-welcome-heading="How can {title} help?"
  data-welcome-subtext="Ask me anything about your properties">
</script>

Painel lateral encaixado

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-display-mode="docked-right"
  data-dock-width="420"
  data-bubble-style="pill"
  data-bubble-label="Ask REDA AI"
  data-welcome-subtext="Ask me anything about your properties">
</script>

Um painel de altura total desliza a partir da borda direita quando o visitante clica na pílula; a página continua legível ao lado dele. Omita data-dock-width para deixar o painel se ajustar sozinho à tela, ou troque por docked-left para encaixar do outro lado. Observe que data-panel-width e data-panel-height não se aplicam aqui — um painel encaixado é sempre de altura total, e data-dock-width define sua largura.

Cores de marca personalizadas com tema escuro

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-theme="dark"
  data-primary-color="#6C63FF"
  data-title="Support Agent"
  data-position="bottom-left">
</script>

Cabeçalho colorido sem hero de boas-vindas

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-bubble-style="pill"
  data-bubble-label="Chat with us"
  data-show-welcome-hero="false"
  data-primary-color="#D32F2F">
</script>

Internacionalizado (espanhol)

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-title="Asistente"
  data-bubble-style="pill"
  data-bubble-label="Pregunte"
  data-input-placeholder="Escribe un mensaje..."
  data-welcome-heading="¿Cómo puede {title} ayudarte?"
  data-welcome-subtext="Pregúntame sobre tu cuenta"
  data-aria-open="Abrir chat"
  data-aria-close="Cerrar chat"
  data-aria-send="Enviar mensaje"
  data-error-generic="Algo salió mal. Inténtalo de nuevo.">
</script>

Como testar as personalizações

Adicione ou modifique atributos data-* na tag de script de incorporação
Atualize sua página (atualização forçada com Ctrl+Shift+R ou Cmd+Shift+R para ignorar o cache)
Verifique se o balão, o cabeçalho e o hero de boas-vindas aparecem conforme o esperado
Teste em tamanhos de tela de desktop, tablet e celular
Teste em vários navegadores (Chrome, Firefox, Safari, Edge)
Envie uma mensagem de teste para verificar se o funcionamento do chat continua correto

Atualização de cache

O carregador do widget inclui invalidação de cache automática que atualiza a cada 5 minutos por padrão (configurável via data-cache-ttl-minutes). Se você não vir suas alterações imediatamente, aguarde alguns minutos ou faça uma atualização forçada.

Perguntas frequentes

Não. O widget usa um Shadow DOM, o que significa que o CSS externo não consegue alcançar seus elementos internos. Toda a estilização é controlada por meio de atributos data-* na tag de script de incorporação.

Carregue a fonte no seu site (por exemplo, via Google Fonts) e defina data-font-family="'Sua Fonte', sans-serif" na tag de incorporação. O widget usará a fonte se ela estiver disponível na página.

Recomenda-se PNG com transparência. JPEG também funciona. Envie uma imagem quadrada (mínimo de 200×200px) para o campo Mascot Image na Definição de Agente. A imagem aparece no balão, no hero de boas-vindas e ao lado das mensagens.

A mensagem de boas-vindas é definida no registro de Definição de Agente no Salesforce (campo External Welcome Message), não no código de incorporação. O título e o subtexto do hero de boas-vindas são separados — esses são definidos por meio de data-welcome-heading e data-welcome-subtext.

Sim. Inclua a tag de script de incorporação apenas nas páginas em que deseja que o widget apareça. Alternativamente, use lógica condicional no template do seu site para incluir ou excluir o script.

Colorido usa sua cor primária (ou header-bg) como plano de fundo do cabeçalho com texto branco. Minimalista usa um plano de fundo branco com texto escuro e uma borda sutil — um visual mais limpo e moderno. Ao usar o estilo minimalista, o atributo data-header-bg é ignorado.

Próximos passos

Revise o guia Configuração do widget externo para a configuração inicial, ou explore Configuração do Agente de Comunidade para implantação no portal.

← Anterior: Configuração do widget externo

Próximo: Configuração do Agente de Comunidade →