Chat Autenticado (Intranet)

O que é

O Chat Autenticado (Intranet) é uma forma de publicar o chatbot dentro de uma plataforma onde os usuários já estão logados (intranet, área do cliente, sistema web, ERP, etc.).

O chat reconhece automaticamente quem é o usuário, sem pedir login novamente, e mantém o histórico de conversa de cada pessoa separado e seguro.

1. Quando usar

Use o modo Intranet quando você quer que:

• O atendimento já comece sabendo quem é o usuário (sem formulário de identificação);
• O histórico de conversas fique vinculado ao ID do usuário no seu sistema;
• Ninguém consiga se passar por outro usuário ou ver a conversa de terceiros.

2. Configurando na plataforma

1. Acesse o seu Projeto → menu Chatbots → selecione o chatbot desejado.
2. Clique na aba Publicar e depois na sub-aba Sites.
3. Clique em Adicionar.
4. No modal “Publicar em Sites ou Sistemas Web”, preencha:
   • Nome da publicação: um nome interno para identificar essa conexão (ex.: “Portal do Cliente”);
   • Tipo de integração: selecione “Intranet (Acesso Autenticado)”.
5. Clique em Salvar Publicação.

Pronto! A nova conexão aparece na Listagem de publicações.

3. O que a plataforma mostra depois de criar

Ao expandir a publicação criada, você verá dois dados essenciais e exemplos de código:

3.1 Project ID

Identificador público do seu projeto. Pode aparecer no código da página sem problema.

3.2 Secret Token (Intranet)

A chave secreta da integração. É ela que o servidor da sua plataforma usa para autenticar os usuários no chat.

⚠️ Nunca coloque o Secret Token no código do navegador (HTML/JavaScript). Ele deve ficar apenas no backend da sua aplicação. Se ele vazar, qualquer pessoa poderá gerar acessos em nome dos seus usuários.

3.3 Exemplos de código

O card exibe um exemplo de chamada backend e um exemplo de script frontend. Eles correspondem ao Modo A de integração — existem duas formas de colocar o chat na sua plataforma, explicadas na seção 5.

4. Como tudo se conecta

┌─────────────────────┐   1. usuário logado    ┌──────────────────────┐
│  Usuário na sua     │ ─────────────────────▶ │  Backend da sua      │
│  plataforma         │                        │  plataforma          │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ 2. POST /intranet-auth
                                                          │    (Secret Token + dados do usuário)
                                                          ▼
                                               ┌──────────────────────┐
                                               │  API Caramelo        │
                                               │  → valida o segredo  │
                                               │  → cria/identifica   │
                                               │    o contato         │
                                               │  → devolve o token   │
                                               └──────────┬───────────┘
                                                          │ 3. real_time_access_token (24h)
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Sua página HTML     │
                                               │  recebe o token e    │
                                               │  carrega o script    │
                                               └──────────┬───────────┘
                                                          │ 4. chat abre já identificado
                                                          ▼
                                               ┌──────────────────────┐
                                               │  Chatbot com o       │
                                               │  histórico daquele   │
                                               │  usuário             │
                                               └──────────────────────┘

Em resumo:

1. O usuário faz login normalmente na sua plataforma;
2. O seu backend chama a API da Caramelo com o Secret Token e os dados do usuário;
3. A API devolve um token temporário exclusivo daquele usuário (campo real_time_access_token);
4. Sua página recebe esse token e o passa ao script do chat (parâmetro secure_connection_token);
5. O chat abre já identificado, com o histórico de conversas daquela pessoa.

📌 Atenção: um mesmo token, dois nomes.

Onde ele aparece	Nome usado
Na resposta da API (seu backend recebe)	real_time_access_token
No script do chat (sua página envia)	secure_connection_token

É o mesmo valor: o seu backend recebe real_time_access_token e a sua página o repassa ao script como secure_connection_token. Ao longo deste guia, sempre que você vir secure_connection_token, leia-se: “o real_time_access_token que a API devolveu”.

💡 Dica: o token deve ser gerado a cada carregamento de página (ele expira em 24 horas). Não reutilize tokens antigos nem compartilhe um mesmo token entre usuários diferentes.

5. As duas formas de integração

Existem dois modos de colocar o chat autenticado na sua plataforma. Os dois usam a mesma chamada intranet-auth no backend — o que muda é como o token chega até o script do chat:

🤔 Não sabe qual escolher? Se a sua página é gerada no servidor a cada acesso, use o Modo A (mais simples). Se a sua aplicação roda no navegador (React, Vue, Angular) ou você quer controlar o momento de abertura do chat, use o Modo B.

5.1 Modo A — Token injetado pelo servidor (SSR)

Passo 1 — Backend: ao renderizar a página, seu servidor chama a API da Caramelo com os dados do usuário logado:

curl -X POST https://api.carameloai.com/api/chatbox/project/{PROJECT_ID}/intranet-auth \
  -H "Authorization: Bearer {SECRET_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "user-123",
    "name": "Nome do Usuário",
    "email": "usuario@exemplo.com"
  }'

Passo 2 — Frontend: seu servidor injeta o token retornado no HTML da página, junto com o script do chat:

<script>
  var carameloaiChatbot = {
    secure_connection_token: "<realtime_access_token_entra_aqui>",
    project_id: "SEU_PROJECT_ID",
    pluginVersion: "VERSAO_DO_PLUGIN"
  };
</script>
<script src="https://static.carameloai.com/prod/index.js"></script>

O script carrega, lê a configuração e abre o chat automaticamente, já identificado.

5.2 Modo B — Sob demanda (Async)

┌──────────────────┐  1. abre a página   ┌───────────────────────────┐
│  Usuário logado  │ ──────────────────▶ │  Página carrega client.js │
└──────────────────┘                     │  (nada aparece ainda)     │
                                         └────────────┬──────────────┘
                                                      │ 2. CarameloChatbotClient.start()
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  SDK faz POST no SEU      │
                                         │  endpoint (mesma origem)  │
                                         └────────────┬──────────────┘
                                                      │ 3. seu backend chama o
                                                      │    intranet-auth (com o Secret)
                                                      ▼
                                         ┌───────────────────────────┐
                                         │  Token volta ao navegador │
                                         │  → chat abre identificado │
                                         └───────────────────────────┘

Passo 1 — Backend: crie um endpoint no seu domínio (ex.: /api/chatbot-token). Ele identifica o usuário logado pela sessão, chama o intranet-auth e devolve o token:

// Exemplo em Node.js / Express
app.post('/api/chatbot-token', async (req, res) => {
  const user = req.user; // usuário já autenticado na SUA plataforma
  if (!user) {
    return res.status(401).json({ error: 'unauthenticated' });
  }

  const response = await fetch(
    'https://api.carameloai.com/api/chatbox/project/SEU_PROJECT_ID/intranet-auth',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer SEU_SECRET_TOKEN', // nunca exposto ao navegador
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        external_customer_id: user.id,
        name: user.name,
        email: user.email
      })
    }
  );

  const data = await response.json();
  res.json({ real_time_access_token: data.real_time_access_token });
});

Passo 2 — Frontend: carregue o client.js apontando para o seu endpoint e inicie o chat quando quiser:

<script>
  var carameloaiChatbot = {
    project_id: "SEU_PROJECT_ID",
    auth_endpoint: "/api/chatbot-token",  // endpoint no SEU domínio
    on_error: function (err) {
      console.error("Falha ao iniciar o chat", err);
    }
  };
</script>
<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  // O chat só abre quando você mandar — ex.: ao clicar num botão:
  document.getElementById("abrir-chat").addEventListener("click", function () {
    CarameloChatbotClient.start();
  });
</script>

6. Configurações visuais do chat

Na mesma tela da publicação, você também pode ajustar o comportamento do widget (clique em Salvar após alterar):

• Posição do chat no site: canto da tela onde o balão aparece;
• Iniciar e manter a caixa de conversa aberta: o chat fica sempre aberto, sem opção de fechar;
• Modo Compacto: o chat ocupa o menor tamanho possível;
• Retenção de Atenção: após um tempo de inatividade, a aba do navegador chama atenção e o chat fica brilhando;
• Renderizar em um local fixo da página: em vez de flutuar, o chat é exibido dentro de uma <div> específica do seu layout.

7. Perguntas frequentes