← Voltar às documentações

Como embutir o widget Web Chat no site

Exemplos para colar o script com Next.js, Vue e PHP.

Como embutir o widget Web Chat no site

Depois de criar a integração Web Chat e copiar o snippet do painel, você só precisa carregar um script no HTML final da página. Não é necessário npm, bundler ou SDK no projeto do cliente: o OSBChat hospeda widget.js e a comunicação com a API é interna ao script.

Por que Next.js, Vue e PHP? Cobrem os cenários mais comuns: app React com SSR (Next), SPA Vue, e sites ou CMS em PHP (WordPress, Laravel Blade, etc.). O padrão é o mesmo: uma tag <script> com atributos data-*.

Atributos do script (referência)

AtributoObrigatórioDescrição
srcSimURL absoluta para …/widget.js no seu domínio OSBChat.
deferRecomendadoCarrega após o HTML; evita bloquear render.
data-integration-idSimID numérico da integração (veja no painel).
data-api-baseNãoOrigem da API (ex. https://app.seudominio.com). Se omitido, o widget usa a origem do próprio src.
data-widget-keySe configurou chaveMesmo valor da chave salva na integração (X-Widget-Key).
data-positionNãobr (padrão), bl, tr, tl — canto do botão.
data-primary-colorNãoCor em hex, ex. #0d9488.

Substitua os valores do exemplo abaixo pelos seus (não commite chaves em repositório público; use variáveis de ambiente no build quando possível).

Next.js (App Router)

No layout raiz ou num layout específico, use next/script:

import Script from 'next/script';

const base = process.env.NEXT_PUBLIC_OSBC_BASE_URL ?? 'https://seu-osbchat.com';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR">
      <body>
        {children}
        <Script
          src={`${base}/widget.js`}
          strategy="afterInteractive"
          data-integration-id={process.env.NEXT_PUBLIC_OSBC_WEB_INTEGRATION_ID!}
          data-api-base={base}
          data-widget-key={process.env.NEXT_PUBLIC_OSBC_WIDGET_KEY ?? ''}
        />
      </body>
    </html>
  );
}

Defina as variáveis em .env.local. Se não usar chave pública no front, deixe data-widget-key vazio só em dev ou prefira injetar o snippet por CMS sem versionar a chave.

Vue 3 (SPA ou Vite)

Em index.html, antes de </body>:

<script
  src="https://seu-osbchat.com/widget.js"
  defer
  data-integration-id="123"
  data-api-base="https://seu-osbchat.com"
  data-widget-key="SUA_CHAVE"
></script>

Ou montar dinamicamente no App.vue com onMounted se os valores vêm de uma API de configuração sua (ainda assim o resultado é uma tag script com os mesmos atributos).

PHP (ex.: WordPress, Laravel, layout comum)

No rodapé do tema ou template, uma vez por página que deve exibir o chat:

<?php
$osb_base = 'https://seu-osbchat.com';
$osb_integration_id = getenv('OSBC_WEB_INTEGRATION_ID') ?: '123';
$osb_widget_key = getenv('OSBC_WIDGET_KEY') ?: '';
?>
<script
  src="<?php echo htmlspecialchars($osb_base, ENT_QUOTES); ?>/widget.js"
  defer
  data-integration-id="<?php echo htmlspecialchars($osb_integration_id, ENT_QUOTES); ?>"
  data-api-base="<?php echo htmlspecialchars($osb_base, ENT_QUOTES); ?>"
  <?php if ($osb_widget_key !== ''): ?>
  data-widget-key="<?php echo htmlspecialchars($osb_widget_key, ENT_QUOTES); ?>"
  <?php endif; ?>
></script>

Use getenv, .env do framework ou opções do CMS para não expor a chave no código versionado.

CORS

O domínio da página onde o visitante abre o site deve estar em Origens permitidas na integração. Ex.: se o site é https://loja.com, inclua https://loja.com (e https://www.loja.com se usar os dois).

Ver também