Canal Widget — Visão geral

O canal Widget recebe pedidos de assistência e de orçamento a partir do site. Os visitantes abrem um chat no site; as mensagens chegam à Quoting24 como tickets e os operadores respondem a partir da interface habitual, com a mesma lógica dos outros canais.

A interface corre num iframe. O site anfitrião só precisa de um script e, quando os dados já são conhecidos, de uma chamada a init(). Não são necessários Angular, um cliente Supabase nem acesso direto à base da Quoting24.

Que integração é necessária

Associar uma empresa e restaurar o histórico são operações distintas. external_id, company_name, name, phone e email não autorizam o acesso às conversas de outra pessoa. Um utilizador já autenticado no site continua a ser um convidado do widget até o site passar uma credencial de restauro válida.

Caso	O que implementar	Continuidade	Secção
Site público, visitante desconhecido	Só o script. O visitante preenche o formulário de contacto.	Sessão de convidado no mesmo browser	Widget B2C
Site que já conhece o perfil e a empresa	Script e `init()` com o perfil e os dados da empresa	Sessão de convidado pré-preenchida e associação de empresa	Widget B2C
Portal com histórico pessoal entre dispositivos	Também uma integração de backend para `external_user_id` e `restore_id`	Histórico pessoal no canal widget autorizado	Widget B2B
Contrato dos campos, CSP, login/logout, provisioning	Guia para programadores	—	Integração técnica

Mostra um botão flutuante ou um chat incorporado na página
Para um visitante novo abre o formulário com as etiquetas Telefone e Nome. Em init() os campos chamam-se phone e name; o e-mail, se o site o conhecer, chama-se email
Se o site chama init(), usa os dados já disponíveis e pode ligar o contacto a uma empresa através de external_id (web_code). Se a empresa não existir e também chegar company_name, pode criá-la
Abre uma conversa gerida na Quoting24 como os outros canais
Aceita anexos PDF, DOC/DOCX, JPG/JPEG e PNG, até 10 MiB por ficheiro e 100 MiB de anexos referenciados por conversa
Mostra a saudação, a mensagem de boas-vindas e, fora de horário, o banner configurado. A composição de mensagens continua disponível

O loader guarda a credencial de convidado no localStorage do site, separada por chave de widget. Se o armazenamento estiver bloqueado, a continuidade pode limitar-se à página atual. A sessão de convidado permite reler a conversa mais recente depois de a fechar, no mesmo browser. Outro dispositivo exige o restauro autenticado.

Onde se configura na Quoting24

Abre Definições → Canais
Seleciona o canal Widget
Abre a configuração

A partir daí definem-se:

logótipo, cor principal, posição do botão
mensagem de saudação, mensagem de boas-vindas, mensagem fora de horário
domínios permitidos
código de incorporação (URL completo do script e chave pública do widget)

Os horários do canal determinam o banner fora de horário.

Pede ao administrador o código de incorporação e os domínios autorizados, incluindo testes e desenvolvimento local. Usa o URL e a chave do mesmo ambiente. Nos exemplos, substitui HOST_WIDGET e CHAVE_PUBLICA_WIDGET pelos valores recebidos.

Os domínios autorizados são nomes de host, por exemplo shop.example.com ou localhost, sem https://, porta, caminho ou prefixo *.. example.com autoriza também os subdomínios. Uma lista vazia não aplica restrições de domínio. Para o teste local serve a página por HTTP: abri-la como ficheiro não chega.

O logótipo, a cor, a posição e as mensagens configuram-se na Quoting24. O company_name passado a init() é a denominação social do cliente, não o título do widget. Não existe um parâmetro público language ou locale: a interface atual está em italiano.

Duas formas de o mostrar no site

Botão flutuante

O script acrescenta o botão depois de carregar as definições gráficas. Um clique abre o chat. No telemóvel o chat flutuante pode ocupar o viewport.

Ver Widget B2C.

Chat incorporado

O chat ocupa um contentor da página, com altura explícita. Não há botão flutuante: o layout e o título vêm do site. Neste modo open(), close() e toggle() não têm efeito. O site controla a altura e a largura do contentor.

Ver Widget B2C.

Uma só instância por página: o loader expõe um único window.Quoting24Widget. Um segundo script não cria um segundo widget.

Chave pública e segredos

Valor	Onde está	Para que serve
Chave pública do widget	URL do script	Seleciona o canal. É pública: não é uma credencial pessoal nem um segredo de integração de backend
Segredo privado da integração	Só no backend do site	Autoriza criar e reutilizar `restore_id`
`restore_id`	Arquivo privado por utilizador, no backend	Credencial com que se restaura o histórico dessa pessoa nesse widget
Credencial de sessão de convidado	`localStorage` do site, gerida pelo loader	Continuidade de convidado no mesmo browser, por chave de widget

Fluxo para o operador

O visitante abre o chat no site e envia uma mensagem
Na Quoting24 nasce ou continua um ticket no canal Widget
Se a inicialização resolveu um external_id, o contacto fica ligado à empresa com esse web_code. Uma empresa acabada de criar pelo widget tem denominação social e, se foi enviado, e-mail; uma empresa já existente não é renomeada por init()
O operador trata o pedido e responde a partir do chat
O cliente vê as respostas no widget

As mensagens do widget só se apagam para todos.

O dado chega do browser e o visitante pode alterá-lo. A ligação à empresa não prova a identidade e não abre o histórico dos outros contactos dessa empresa.

Por onde começar

Configura o aspeto, os horários e os domínios em Definições → Canais → Widget
Site público ou portal que pré-preenche o perfil: Widget B2C
Histórico da mesma pessoa noutro browser: Widget B2B
Campos, criação de empresa, CSP e lista de verificação: Integração técnica