Guia de implementação

A sessão é identificada por origem (domínio) e appId, ambos configurados com o Marco de antemão. O widget é carregado com uma única tag de script e começa sozinho, sem chamar nenhuma API JavaScript.

Quando usar

Landing pages, sites informativos, portais sem login.

Configuração

Vive no backend do Marco, associada ao seu appId.

Renderização

Sempre uma bolha flutuante ancorada à viewport.

Backend próprio

Nenhum é necessário.

Integração básica

Adicione estas duas tags à sua página, uma no head e outra no body. É só isso: nenhuma outra chamada é necessária.

<html>
  <head>
    <script
      src="https://production.deep-talk.ai/widget/widget.js"
      defer>
    </script>
  </head>
  <body>
    <marco
      id="my-marco-widget"
      api-base-url="https://production.deep-talk.ai/widget"
      app-id="YOUR_APP_ID">
    </marco>
  </body>
</html>

Substitua YOUR_APP_ID pelo identificador que o Marco fornece. Carregar o script é suficiente: o widget aparece automaticamente como bolha flutuante.

Ciclo de vida e persistência

A sessão é criada assim que o widget termina de carregar. Cada navegador mantém uma única conversa contínua, identificada pelo seu próprio session_id.

Identificador anônimo

O widget gera um identificador de sessão aleatório na primeira vez que carrega em um navegador e o guarda no localStorage. Ele não está vinculado a nenhuma identidade real: serve apenas para retomar a conversa naquele mesmo navegador e como identificador de correlação para eventos e auditoria.

Retomada

Recarregar a página, navegar e voltar, ou fechar e reabrir a aba ou o navegador (mesmo perfil): em todos esses casos o widget encontra o identificador guardado e, se a sessão ainda estiver dentro do seu tempo limite de inatividade, retoma a conversa e publica SESSION_RELOADED em vez de SESSION_CREATED.

Tempo limite de inatividade

Uma sessão sem atividade além do limite configurado é encerrada automaticamente. O carregamento seguinte do widget naquele navegador já não encontra sessão para retomar e publica SESSION_CREATED.

Encerramento explícito

Por padrão a sessão só termina por inatividade ou por ação do usuário dentro do widget. Se você precisar encerrá-la de forma programática, use MarcoWidget.finish().

API opcional: MarcoWidget

Para a maioria das integrações, a seção anterior é tudo o que é preciso. Se a sua aplicação precisa reagir a eventos ou encerrar a sessão explicitamente, o script expõe um namespace global opcional, MarcoWidget, em window.

MarcoWidget.on('READY', function () {
  console.log('Widget Marco pronto');
});

MarcoWidget.on('SESSION_CREATED', function (msg) {
  console.log('Nova sessão:', msg.session_id);
});

// Encerra a sessão e limpa o identificador do localStorage.
// O próximo carregamento inicia uma sessão nova.
MarcoWidget.finish();

MarcoWidget.on() inscreve um callback nos eventos de estado e cuida da verificação de origem para você. Neste fluxo a sessão já está ativa quando o script carrega, então MarcoWidget serve apenas para ouvir eventos e, opcionalmente, encerrar a sessão.

Eventos

O widget publica o estado da sessão com postMessage, emitido do seu iframe para a janela que o contém. MarcoWidget.on() é um wrapper sobre esse mesmo fluxo.

Estrutura da mensagem

READY, STARTED, CANCELLED e ERROR compartilham esta estrutura base. session_id está ausente em READY e presente a partir de SESSION_CREATED ou SESSION_RELOADED.

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "READY",
  "session_id": "sess_9f2a1c",
  "timestamp": "2026-08-20T14:32:04Z"
}

COMPLETED acrescenta dois campos sobre a base: created_at e finished_at.

Erros

Os erros chegam como um evento de estado ERROR, na mesma estrutura acima, com os campos code e message.

Segurança

A origem é o sinal de confiança primário deste fluxo. Cada carregamento do widget é comparado com os domínios autorizados para o appId informado, e toda requisição de uma origem fora dessa lista é rejeitada com unauthorized_origin. O Marco também aplica limites de taxa por appId e por endereço IP.

O script e suas chamadas são servidos apenas por HTTPS, e a sua aplicação deve ser servida por HTTPS em todos os ambientes. O widget roda dentro de um iframe em sandbox com permissões mínimas, gerenciado automaticamente pelo script carregador.

Se a sua aplicação aplica uma Content-Security-Policy, autorize o domínio do widget nas três diretivas que governam o carregamento do script, a incorporação do iframe e as chamadas de rede do widget.

Content-Security-Policy:
  script-src  https://production.deep-talk.ai;
  frame-src   https://production.deep-talk.ai;
  connect-src 'self' https://production.deep-talk.ai;

Seu frontend inicia e gerencia a sessão diretamente, chamando o MarcoWidget com uma identidade de usuário assinada pelo seu backend. O navegador recebe a assinatura, nunca o segredo.

Quando usar

Seu frontend já gerencia a sessão autenticada do usuário.

Autenticação

HMAC-SHA256, verificada pelo Marco em cada chamada.

Renderização

Flutuante ou inline via component_id.

Backend próprio

Apenas para calcular a assinatura. Sem endpoint dedicado.

Carregar o script

Esta tag carrega o shell do widget. A sessão é iniciada separadamente, com a chamada a init. Nenhuma interface visível é renderizada até lá.

<html lang="en">
  <head>
    <meta charset="utf-8">
    <script src="https://production.deep-talk.ai/widget/widget.js"
            defer onload="initializeMarco()"></script>
  </head>
  <body>
    <script>
      const signature = '<SIGNATURE_FROM_BACKEND>';
      const timestamp = '<TIMESTAMP_FROM_BACKEND>';

      function initializeMarco() {
        window.$MarcoWidget.init({
          apiBaseUrl: 'https://production.deep-talk.ai/widget',
          appId:      'marco-demo',
          floating:   true,
          user_id:    '323232',
          created_at: timestamp,
          signature:  signature,
        });
      }
    </script>
  </body>
</html>

Onde chamar init e finish

1. Carregue o script em qualquer ponto da sua página.
2. Assim que o script tiver carregado e a sessão do seu usuário estiver disponível, chame init(), normalmente no mesmo lugar onde você já trata a autenticação: um handler de login bem-sucedido, um efeito de React, um callback de auth.
3. Em mudanças de contexto, chame init() novamente com o novo external_id.
4. No logout, chame finish(), que encerra a sessão ativa e limpa os dados armazenados localmente.

Autenticação assinada

Seu backend calcula localmente uma assinatura HMAC-SHA256 com um segredo compartilhado emitido pelo Marco, e seu frontend a envia junto com o user_id. Trate o segredo como uma chave de API do lado do servidor: leia-o do seu gerenciador de segredos e nunca o envie ao frontend, a um cliente mobile ou a terceiros.

// Fórmula base
signature = HMAC-SHA256(shared_secret, user_id)

// Com proteção contra repetição (recomendado em produção)
signature = HMAC-SHA256(shared_secret, `${user_id}:${created_at}`)

// Node.js
const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', sharedSecret)  // segredo, como UTF-8
  .update(userId, 'utf8')              // user_id, como UTF-8
  .digest('hex');                      // hexadecimal minúsculo

Tanto o segredo quanto o user_id devem ser codificados em UTF-8 antes de assinar, e a assinatura resultante deve ser representada em hexadecimal minúsculo. Uma assinatura que não respeite essa codificação exata falha na verificação mesmo que o segredo esteja correto.

Proteção contra repetição

Por padrão a assinatura só prova que o user_id foi assinado por alguém de posse do seu segredo, não quando. Passar um created_at opcional fecha essa brecha. É um timestamp UTC em formato ISO 8601 e, quando incluído, deve fazer parte tanto do payload quanto da assinatura. O Marco rejeita chamadas cujo created_at esteja a mais de cinco minutos da hora atual, em qualquer direção.

Parâmetros

Exemplo de metadata

{
  "specialty": "oncology",
  "diagnosis": "HER2-positive breast cancer, stage III",
  "current_treatment": "trastuzumab + pertuzumab, cycle 4 of 6",
  "disease_state": "partial response, stable since last imaging",
  "ecog_status": "1",
  "line_of_therapy": "second line"
}

Prefira chaves descritivas e autoexplicativas a abreviações. O metadata é interpretado pelo agente ao iniciar a sessão, então a clareza aqui melhora diretamente a qualidade das respostas. O exemplo é orientativo: também é possível trabalhar com texto mais extenso ou resumos, se isso representar melhor os seus dados.

Ciclo de vida e persistência

Aplicam-se dois tempos de vida independentes: a janela de validade da assinatura e a sessão em si.

Janela da assinatura

Quando created_at é incluído, a assinatura é válida por cinco minutos a partir da emissão. Ela é recalculada, ou reaproveitada dentro da sua janela, a cada chamada a init ou finish.

Sessão

Corre por um tempo de vida configurado de forma independente uma vez iniciada. Estende-se com a atividade e termina por encerramento explícito, por inatividade ou ao expirar esse tempo de vida.

Mudar de contexto

Para apontar o widget a um paciente ou registro diferente, chame init() com o novo external_id. Isso não atualiza a sessão aberta: é uma sessão distinta, nova ou retomada se aquele contexto já tinha uma ativa.

Recarregar, navegar e fechar a aba

As três ações se comportam igual: o iframe é descartado, mas o identificador persiste no localStorage. A próxima chamada a init() com o mesmo user_id e external_id tenta retomar automaticamente, como efeito dessa mesma chamada.

Encerramento explícito

MarcoWidget.finish() encerra a sessão imediatamente e limpa o identificador guardado. Depois de finish(), uma chamada a init() com o mesmo par inicia uma sessão nova.

Eventos

O widget publica o estado com postMessage do seu iframe para a janela que o contém. O script carregador também expõe MarcoWidget.on(evento, callback), um wrapper sobre esse mesmo fluxo que cuida da verificação de origem para você.

MarcoWidget.on('READY', function () {
  console.log('Widget Marco pronto para receber init()');
});

MarcoWidget.on('SESSION_CREATED', function (msg) {
  console.log('Nova sessão:', msg.session_id);
});

MarcoWidget.on('ERROR', function (err) {
  console.error('Erro do widget Marco:', err.code, err.message);
});

Estrutura da mensagem

session_id e external_id estão ausentes em READY e presentes a partir de SESSION_CREATED ou SESSION_RELOADED.

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "SESSION_RELOADED",
  "session_id": "sess_9f2a1c",
  "external_id": "patient_789",
  "timestamp": "2026-08-20T14:32:04Z"
}

Erros

A assinatura é calculada localmente no seu backend, sem ida e volta ao Marco. Uma assinatura inválida ou vencida é descoberta quando o widget tenta usá-la, e chega como um evento de estado ERROR.

Segurança

O user_id nunca é confiado por si só. O Marco recalcula a assinatura de forma independente e a compara antes de iniciar ou continuar qualquer sessão. Cada chamada a init ou finish também é comparada com os domínios autorizados para a sua conta, e rejeitada com unauthorized_origin se a origem não estiver na lista, mesmo que a assinatura seja válida.

Autorização em nível de aplicação

Uma assinatura válida confirma que o seu backend, de posse do segredo, assinou aquele user_id. Verificar se aquele usuário deve ter acesso ao registro descrito em metadata é responsabilidade da sua própria aplicação, antes de chamar init(). A decisão de acesso é tomada nesse momento; a assinatura apenas a transmite.

Content-Security-Policy

Content-Security-Policy:
  script-src  https://production.deep-talk.ai;   // script de inicialização
  frame-src   https://production.deep-talk.ai;   // iframe em sandbox
  connect-src 'self' https://production.deep-talk.ai;  // chamadas do widget

O script e suas chamadas são servidos apenas por HTTPS. O widget roda em um iframe em sandbox com permissões mínimas, e usa localStorage para a retomada; esse cache é limpo ao chamar finish().

Seu backend cria a sessão diretamente com o backend do Marco. Seu frontend nunca recebe dados do escopo da sessão, apenas um token opaco, de uso único e de curta duração para iniciar o chat.

Quando usar

Quando o contexto clínico deve permanecer no servidor o tempo todo.

Autenticação

Bearer client_secret, de servidor a servidor.

Renderização

Um <iframe> que você controla.

Garantia

Arquitetural: o navegador não tem informação com que construir ou ler esses dados.

Criar a sessão

Seu backend chama o endpoint de sessão do Marco por HTTPS. A credencial é apresentada como bearer token e é de longa duração: é emitida uma vez por cliente, não por sessão.

POST /launch_token
Host: production.deep-talk.ai
Authorization: Bearer <client_secret>
Content-Type: application/json

{
  "app_id": "oncology-widget",
  "user_id": "doctor_123",
  "metadata": {
    "specialty": "oncology",
    "diagnosis": "HER2-positive breast cancer, stage III",
    "current_treatment": "trastuzumab + pertuzumab, cycle 4 of 6"
  }
}

Resposta

{
  "launch_token": "lt_7Kx0mQe2vB…",
  "session_id": "sess_9f2a1c",
  "expires_at": "2026-08-20T14:37:00Z"
}

launch_token é opaco, de uso único e de curta duração, e não contém nenhum dado subjacente da sessão. Guarde o session_id para correlacioná-lo com os seus próprios registros de auditoria; você não precisará dele de novo para interagir com o widget.

Incorporar o iframe

Seu frontend exibe um iframe apontado para a URL de sessão com o launch_token anexado. O token na URL é a única entrada que este fluxo exige do seu frontend. Aplique codificação de URL ao valor, já que ele pode conter caracteres que exigem codificação percentual.

<iframe
  src="https://production.deep-talk.ai/chat?launch_token=lt_7Kx0mQe2vB%2E…"
  sandbox="allow-scripts allow-same-origin allow-forms"
  allow="clipboard-write"
  referrerpolicy="no-referrer"
></iframe>

Validação

Quando o iframe carrega, o Marco valida o token antes de exibir qualquer conteúdo.

1. Busca. O Marco procura o launch_token em relação à sessão criada.
2. Validação. Verifica que o token existe, não expirou, não foi utilizado, e que a origem da requisição corresponde aos domínios autorizados para a sua conta.
3. Consumo de uso único. Se for válido, o token é marcado imediatamente como utilizado e não pode ser reutilizado.
4. Início. O Marco devolve o mínimo para renderizar o widget: session_id, estado de pronto e configuração de exibição, gerados a partir do metadata já consumido no servidor.
5. Pronto. O widget passa a ser interativo e publica READY ao contêiner.

Além disso, READY indica apenas que o widget está interativo: o metadata da sessão é processado somente quando o usuário realiza uma ação explícita para começar.

Ciclo de vida e expiração

Aplicam-se dois tempos de vida independentes. O launch_token dura cinco minutos e é de uso único: existe apenas para levar o iframe de "tem uma referência" a "sessão em execução". A sessão corre por um tempo de vida mais longo, configurado por integração, estende-se com a atividade, e termina por encerramento explícito, inatividade ou expiração.

Fechar a aba, recarregar a página ou desmontar o iframe ao navegar produzem o mesmo resultado: o iframe é descartado e a sessão termina com ele. O token já foi consumido assim que o carregamento anterior teve sucesso, então não pode ser reutilizado. Seu frontend deve solicitar uma nova sessão ao seu backend, que emite um novo token com o contexto atualizado. Se, em vez disso, o seu contêiner mantém o iframe montado durante a navegação, a sessão continua ativa até o seu tempo limite de inatividade ou o encerramento explícito.

Mudar de contexto

O metadata é fixado ao criar a sessão e não pode ser atualizado em uma sessão em execução. Para apontar o widget a um paciente ou registro diferente, solicite uma nova sessão com o novo contexto.

Eventos

O widget publica o estado diretamente à janela que o contém com postMessage. Sua página escuta com um listener padrão. Verifique sempre event.origin antes de ler event.data, nunca o compare com '*', e nunca confie em uma mensagem que não inclua source: 'marco-widget'.

const MARCO_ORIGIN = 'https://production.deep-talk.ai';

window.addEventListener('message', (event) => {
  if (event.origin !== MARCO_ORIGIN) return;
  const msg = event.data;
  if (msg?.source !== 'marco-widget') return;

  switch (msg.state) {
    case 'READY':     /* o widget está interativo */      break;
    case 'STARTED':   /* o usuário enviou uma consulta */ break;
    case 'COMPLETED': /* sessão finalizada */             break;
    case 'CANCELLED': /* cancelada por usuário ou app */  break;
    case 'ERROR':     /* ver a seção de erros */          break;
  }
});

Enviar comandos ao widget

Seu contêiner pode enviar comandos da mesma forma, dirigidos ao contentWindow do iframe. Passe sempre a origem de destino exata como segundo argumento, nunca '*', para que o navegador se recuse a entregar a mensagem se o iframe tiver navegado para outro lugar de forma imprevista.

const iframeWindow = document.querySelector('iframe').contentWindow;

iframeWindow.postMessage({
  source: 'marco-host',
  version: 1,
  type: 'COMMAND',
  action: 'CLOSE',          // única ação suportada atualmente
  session_id: 'sess_9f2a1c'
}, MARCO_ORIGIN);

Ao recebê-lo, o widget verifica a origem contra as autorizadas para a sua conta antes de executá-lo. Um comando vindo de uma origem não registrada é descartado em silêncio: o widget não age nem emite ERROR, já que uma origem não reconhecida pode não ser um emissor legítimo. Um CLOSE válido encerra a sessão imediatamente e o widget emite CANCELLED de volta, para que o seu contêiner tenha uma confirmação limpa e correlacionável.

O payload de COMPLETED

{
  "source": "marco-widget",
  "version": 1,
  "type": "STATE_CHANGE",
  "state": "COMPLETED",
  "session_id": "sess_9f2a1c",
  "created_at": "2026-08-20T14:32:00Z",
  "finished_at": "2026-08-20T14:36:12Z",
  "metadata": {
    "query_summary": "Asked about second-line options for HER2-positive…",
    "final_synthesis": "Reviewed second-line options for HER2-positive…"
  }
}

Erros

Os erros ocorrem em dois momentos e se apresentam de forma diferente em cada um. Na criação da sessão são respostas HTTP padrão à sua chamada de servidor a servidor.

A partir da validação do iframe, os erros chegam como um evento de estado ERROR com os campos code e message.

Segurança

Tanto a criação de sessão quanto a incorporação do iframe acontecem apenas por HTTPS. O conteúdo misto é rejeitado pelo navegador antes que o Marco participe. Cada validação de token compara a origem solicitante com os domínios autorizados para a sua conta, e rejeita com unauthorized_origin mesmo que o token seja válido.

Autorização em nível de aplicação

Um launch_token válido apenas confirma que o client_secret do seu backend foi apresentado corretamente. Não garante que aquele user_id deva ter acesso ao registro descrito em metadata: essa verificação é responsabilidade exclusiva da sua aplicação, no momento em que o seu backend chama o endpoint. Uma vez criado o token, a decisão de acesso já foi tomada; o token apenas a transmite.

Content-Security-Policy

Neste fluxo a sua página nunca chama o Marco diretamente: só o fazem o seu backend e o próprio iframe. Por isso a CSP da sua página contêiner só precisa autorizar a origem do Marco em frame-src.

Content-Security-Policy:
  frame-src https://production.deep-talk.ai;

Sem cookies

O iframe mantém a sua credencial de sessão em memória depois do início e a anexa explicitamente a cada chamada posterior, evitando as restrições de cookies de terceiros.