Configuração do widget externo
Financiamento e uso de IA
IA incluída usa créditos REDA. Traga sua própria IA usa a conta de provedor da sua organização, cobrada diretamente pelo provedor. A licença define um modelo para toda a organização. Nos dois, o REDA AI governa ferramentas e ações configuradas no Salesforce. Configure a licença e as contas de IA.
Se o administrador mudar a conexão efetiva, o modelo ou o financiamento, as sessões afetadas precisarão de nova conversa. Inicie-a quando solicitado; a conversa antiga não pode simplesmente continuar na nova rota. Em contas próprias, confira o acesso às credenciais do convidado do site ou usuário autenticado do portal. Veja as permissões.
Um agente com Channel = External_Widget fica vinculado apenas à superfície pública do widget. Ele não pode ser invocado a partir do LWC interno do Salesforce, de um Flow / Apex (canal de API) ou de uma página de comunidade/portal. Por outro lado, o endpoint REST público (/chat/v1/*) só aceita agentes cujo Channel esteja definido como External_Widget — encaminhar um agente Interno, de API ou de Comunidade por essa superfície é rejeitado com um erro claro. Escolha o canal que corresponde à superfície em que você pretende implantar.
O que é o Widget Externo?
O Widget Externo permite incorporar um widget de chat da REDA AI ao seu site, portal ou aplicação web. Os visitantes podem fazer perguntas, pesquisar seus dados e obter ajuda — tudo sem fazer login no Salesforce.
- Não requer autenticação — Os visitantes conversam sem login no Salesforce
- Acesso de convidado — Usa um perfil de Usuário Convidado configurado, com permissões limitadas e controladas
- Restrições de origem — Você controla exatamente quais domínios podem incorporar o widget
- Totalmente configurável — Cores, texto, layout, estilo do balão e tela de boas-vindas são todos personalizáveis via atributos de incorporação
- Responsivo para dispositivos móveis — Adapta-se automaticamente a telas móveis, com modo de tela cheia opcional
Visão geral da configuração
-
Configure a Definição de Agente
Defina o canal como External_Widget e configure as origens permitidas, a mensagem de boas-vindas e as ferramentas.
-
Gere a chave de API
Crie uma Chave de API Externa que o widget usa para se autenticar.
-
Incorpore o widget
Adicione uma única tag de script ao seu site com a chave de API e o endpoint.
-
Personalize a aparência
Adicione atributos
data-*opcionais para controlar cores, layout, estilo do balão e tela de boas-vindas.
Etapa 1: configure a Definição de Agente
- Navegue até o objeto REDAAI Agent Definition no Setup
- Abra ou crie um registro de Definição de Agente
- Defina Canal como
External_Widget - Defina Origens Permitidas com o(s) domínio(s) onde o widget será incorporado (ex.:
https://example.com, https://www.example.com) - Defina Mensagem de Boas-Vindas Externa com uma saudação para os visitantes (ex.: “Olá! Como podemos ajudar você hoje?”)
- Opcionalmente, envie uma Imagem do Mascote para um avatar personalizado
- Atribua as ferramentas apropriadas (recomenda-se somente leitura para usuários convidados)
- Ative o agente
Etapa 2: gere uma chave de API
O widget se autentica usando uma Chave de API Externa. Consulte Gerenciamento de Chaves de API para os passos detalhados. Você vai precisar de dois valores do registro da chave de API:
- Chave de API — a string da chave gerada
- URL do endpoint — o endpoint REST do Salesforce Sites (formato:
https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1)
Etapa 3: incorpore o widget
Adicione uma única tag <script> ao seu site. O REDA AI Loader cuida de tudo — carrega o widget, aplica sua configuração e inicializa o chat.
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>
Substitua <org> pelo prefixo My Domain do seu org do Salesforce e your-api-key-here pela chave de API real.
Os atributos data-api-key e data-endpoint são obrigatórios. Sem eles, o widget não será carregado.
Essa chave é pública. Ela fica no HTML da sua página, então qualquer pessoa que veja o código-fonte consegue lê-la — isso é proposital em um widget público, e é por isso que a chave sozinha nunca pode ser suficiente para alcançar algo sensível. Quem faz o trabalho de verdade são dois controles: as Origens permitidas, verificadas contra o cabeçalho Origin definido pelo navegador (o JavaScript da página não consegue forjá-lo), de modo que a chave só funciona quando chamada a partir dos seus domínios; e as permissões do próprio usuário convidado, que limitam o que qualquer conversa pode alcançar, independentemente do que se peça ao agente. Configure os dois como se a chave estivesse em um outdoor.
Exemplo de incorporação completa
Você pode adicionar atributos data-* opcionais para personalizar a aparência e o comportamento do widget:
<script
src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
data-api-key="your-api-key-here"
data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
data-title="Support Agent"
data-primary-color="#0070D2"
data-bubble-style="pill"
data-bubble-label="Ask Support"
data-header-style="minimal"
data-welcome-heading="How can {title} help?"
data-welcome-subtext="Ask me anything about your account"
data-theme="light"
data-position="bottom-right"
data-display-mode="bubble">
</script>data-display-mode="docked-right" (ou docked-left) e o assistente abre como um painel de altura total ancorado a essa borda, em vez de um cartão flutuante — útil quando as respostas incluem cards de imóveis ou fotos. O balão de acionamento permanece exatamente onde está. Consulte Modo de Exibição.
Consulte Personalização da Interface do Widget para a lista completa de atributos data-*.
Configurando as origens permitidas
O campo Origens Permitidas na Definição de Agente controla quais domínios podem incorporar o seu widget. Este é um recurso de segurança que impede incorporações não autorizadas.
Origens Permitidas está vazio por padrão, e vazio significa nenhuma restrição — qualquer site que tenha a sua chave de API pode usar o seu agente. Como a chave de API fica visível no código-fonte da sua página (inevitável para qualquer widget incorporável — veja a Etapa 2), qualquer pessoa pode copiá-la do seu site. Preencher o Origens Permitidas é o que impede outro site de usar o seu agente e os seus créditos.
Recomendamos configurá-lo em todo widget em produção.
https://example.com, https://www.example.com, https://support.example.com
O widget é carregado apenas nesses três domínios. Qualquer outro domínio é bloqueado.
- Sempre inclua o protocolo —
https://example.comeexample.comsão tratados de forma diferente - Separe vários domínios com vírgulas
- Liste todos os domínios que seus visitantes realmente usam — se
www.example.comeexample.comservirem ambos o seu site, inclua os dois, ou o widget falhará em um deles - Teste antes de colocar em produção — incorpore primeiro em um domínio de staging para verificar que funciona, e adicione o domínio de staging à lista enquanto faz isso
Quando Origens Permitidas está definido, a REDA AI verifica o site do qual a solicitação realmente veio, conforme reportado pelo navegador do visitante. Uma página não pode alegar ser um site diferente, portanto a sua chave não funcionará se for copiada para o site de outra pessoa.
Duas coisas decorrem disso. Solicitações que não vêm de um navegador são recusadas quando Origens Permitidas está definido — portanto, se você chamar a API de chat diretamente do seu próprio servidor, deixe Origens Permitidas em branco e controle o acesso de outra forma. E uma lista de permissões é apenas uma camada, não a história completa: os limites por conversa, por hora e por dia na Definição de Agente são o que limita o uso caso uma chave seja mal utilizada.
Está atualizando? Se Origens Permitidas estiver em branco — o padrão — nada muda para você. Os widgets continuam funcionando exatamente como antes.
Saiba o que a lista de origens impede e o que não impede. Ela funciona porque o
próprio navegador define o cabeçalho Origin e o JavaScript da página não consegue
sobrescrevê-lo — então uma chave roubada e colada em outro site é recusada. Ela
não impede quem chama a partir de um servidor forjando o cabeçalho, com
curl ou qualquer script. Nenhuma lista de origens impede.
O que limita esse caso é todo o resto: os limites de taxa por sessão e por hora, o teto diário de créditos da organização e revogar a chave. Trate Origens Permitidas como o controle que mantém seu widget nas suas próprias páginas, não como autenticação.
Permissões do usuário convidado
Os agentes de Widget Externo são executados sob um perfil de Usuário Convidado. Esse perfil deve ser configurado com cuidado:
- Acesso limitado a objetos — Conceda acesso apenas aos objetos que os visitantes precisam (ex.: Knowledge, Caso)
- Acesso limitado a campos — Exponha apenas campos públicos e não sensíveis
- Regras de compartilhamento — Usuários convidados só podem ver registros marcados como públicos via regras de compartilhamento
- Acesso de gravação (opcional) — Conceda acesso de criação com moderação (ex.: apenas para criação de Caso)
Sempre revise o perfil de Usuário Convidado e as regras de compartilhamento antes de implantar um Widget Externo. Teste como usuário convidado para verificar exatamente quais dados estão acessíveis.
Ferramentas recomendadas para widgets externos
Seja conservador na atribuição de ferramentas para agentes voltados a convidados:
| Ferramenta | Recomendado? | Notas |
|---|---|---|
soql_query |
Talvez | Somente se os convidados precisarem pesquisar registros públicos (ex.: artigos da base de conhecimento) |
get_record |
Talvez | Se os convidados devem visualizar detalhes de registros públicos específicos |
count_records |
Talvez | Útil para responder a perguntas do tipo “quantos” sobre dados públicos |
create_record |
Raramente | Somente se os visitantes devem criar registros (ex.: casos de suporte). Restrinja a objetos específicos. |
describe_object |
Não | Expõe detalhes do esquema — não é apropriado para usuários externos |
send_email |
Não | Risco de segurança — nunca atribua a widgets externos |
update_record / delete_record |
Não | Convidados não devem modificar ou excluir registros |
web_search |
Opcional | Ative via Allow Web Search na Definição de Agente. Gera custo adicional de créditos por pesquisa. |
Como as ações funcionam no widget externo
O Widget Externo é um canal conversacional, voltado ao cliente, portanto não exibe os cartões de confirmação usados no canal Interno. Em vez disso, o agente executa automaticamente uma ferramenta de Ação e depois responde automaticamente com o resultado real — por exemplo, “Obrigado! Criei sua solicitação como Caso nº 00001234.” Se a ação falhar, ele informa isso com honestidade. O número de turnos de continuação automáticos é limitado pela configuração de plataforma Max Continuation Depth (padrão 3). Como o widget é executado como o usuário convidado compartilhado do Site, atribua ferramentas de Ação com critério e mantenha as permissões de convidado restritas. Consulte Confirmações de Ação → Como as confirmações variam por canal.
Casos de uso comuns
Os visitantes abrem o chat na sua página de suporte. O agente responde a perguntas frequentes, pesquisa artigos da base de conhecimento e se oferece para criar um caso de suporte para questões complexas.
Ferramentas: soql_query, create_record (somente Casos)
Os potenciais clientes no seu site conversam com o agente. O agente qualifica o lead e cria um registro de Lead para acompanhamento.
Ferramentas: soql_query, create_record (somente Leads)
Locatários ou clientes perguntam sobre imóveis, reservas ou detalhes de conta. O agente pesquisa dados públicos e fornece respostas.
Ferramentas: soql_query, get_record
Visão geral da aparência do widget
O widget oferece ampla personalização por meio de atributos data-* na tag de script de incorporação:
- Estilo do balão — Circular (padrão) ou botão em formato de pílula com rótulo de texto
- Estilo do cabeçalho — Colorido (fundo da marca) ou minimalista (branco/limpo)
- Tela de boas-vindas — Tela de boas-vindas personalizada com título, avatar e subtexto opcional
- Cores — Cor primária, fundo do cabeçalho, cor da mensagem do usuário, fundo, texto e bordas
- Tipografia — Família de fonte e tamanho de fonte personalizados
- Dimensões — Largura do painel, altura, tamanho do balão e raio da borda
- Posição — Canto inferior direito ou canto inferior esquerdo
- Tema — Modo claro ou escuro
- Dispositivos móveis — Ponto de quebra configurável e modo de tela cheia opcional
- Texto / i18n — Todos os rótulos, placeholders, textos ARIA e mensagens de erro são personalizáveis
Para detalhes completos e exemplos, consulte Personalização da Interface do Widget.
Boas práticas
Revise cuidadosamente as permissões do perfil de Usuário Convidado. Garanta que nenhum dado sensível seja exposto. Teste o widget como convidado para verificar exatamente quais dados são acessíveis.
Mantenha as ferramentas ao mínimo — Atribua apenas as ferramentas que os convidados realmente precisam. Cada ferramenta aumenta o uso de tokens e a exposição potencial de dados.
Escreva guardrails apropriados — Adicione prompts de Guardrail para restringir o comportamento do agente. Exemplo: “Nunca discuta preços internos. Sempre ofereça conectar o usuário com vendas.”
Monitore as conversas — Revise os registros de conversa regularmente para entender as perguntas dos visitantes. Use os insights para melhorar sua base de conhecimento ou ajustar o comportamento do agente.
Teste em vários dispositivos — Verifique se o widget funciona em desktop, tablet e dispositivo móvel antes de colocar em produção.
Perguntas frequentes
Você adiciona uma única tag <script> à sua página. O REDA AI Loader busca automaticamente o código do widget com cache-busting, aplica sua configuração a partir dos atributos data-* e inicializa o chat. Nenhum JavaScript adicional é necessário.
Sim. Adicione todos os domínios ao campo Origens Permitidas na Definição de Agente (separados por vírgula). Use o mesmo código de incorporação em cada site.
A API rejeitará solicitações de domínios não listados em Origens Permitidas. O widget não funcionará em domínios não autorizados.
Sim. Crie registros de Definição de Agente separados, cada um com sua própria chave de API e origens permitidas. Cada site recebe seu próprio código de incorporação apontando para a chave de API e o endpoint apropriados.
Sim. O widget é anexado à página uma vez no carregamento e persiste entre as mudanças de rota. Ele usa um Shadow DOM, portanto não entra em conflito com os estilos ou o JavaScript da sua aplicação.
Sim. Toda a personalização é 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. Consulte Personalização da Interface do Widget para ver todas as opções.
Próximos passos
Personalize a aparência do seu widget com Personalização da Interface do Widget, ou revise Acesso a Dados e Permissões para proteger a configuração do seu usuário convidado.