Integração Web Autenticada

Visão Geral

Este guia descreve os passos necessários para implementar o chat da Caramelo AI de forma segura dentro da sua intranet ou área logada, utilizando o fluxo autenticado (Server-to-Server).

Esse fluxo garante que apenas usuários autenticados no seu sistema possam acessar o chatbot e que o histórico de conversas seja mantido de forma segura e atrelado ao usuário.

Como Funciona

O processo consiste em duas etapas principais:

1. Backend (Server-to-Server): O seu servidor se comunica com a API da Caramelo AI enviando os dados do usuário autenticado e um token secreto. A nossa API retorna um token de conexão temporário (real_time_access_token).
2. Frontend: O seu servidor injeta esse token temporário no HTML da página. O SDK da Caramelo AI utilizará esse token para iniciar a conexão segura do chatbot.

┌──────────────┐       POST /intranet-auth       ┌──────────────────┐
│  Seu Backend │ ──────────────────────────────► │  API Caramelo AI │
│              │ ◄────────────────────────────── │                  │
│              │     real_time_access_token       │                  │
└──────┬───────┘                                  └──────────────────┘
       │
       │  Injeta token no HTML
       ▼
┌──────────────┐
│   Frontend   │ ──► SDK authenticated.js ──► WebSocket seguro
│   (Browser)  │
└──────────────┘

Pré-requisitos

Antes de começar, certifique-se de que possui:

⚠️ Atenção: O secret_token deve ser mantido em segredo no seu backend e NUNCA exposto no frontend.

Passo 1: Autenticação no Backend (Server-to-Server)

Quando o usuário acessar a página do chat, o seu servidor deve fazer uma requisição POST para a API da Caramelo AI antes de renderizar a página.

Endpoint

POST https://api.carameloai.com/api/chatbox/project/{project_id}/intranet-auth

Substitua {project_id} pelo ID do seu projeto.

Headers

{
  "Content-Type": "application/json"
}

Body (JSON)

{
  "secret_token": "SEU_SECRET_TOKEN",
  "external_customer_id": "12345",
  "name": "João da Silva",
  "email": "joao@email.com",
  "lang": "pt"
}

Parâmetros

Resposta de Sucesso (200 OK)

{
  "real_time_access_token": "eyJhbGciOiJIUzI1NiIsIn...",
  "customer_id": "c_...",
  "chat": { ... },
  "chatbot": { ... }
}

O valor que você precisará usar no próximo passo é o real_time_access_token.

Passo 2: Configuração no Frontend

Com o real_time_access_token retornado pela API, o seu servidor deve injetá-lo como secure_connection_token no HTML da página onde o chatbot será exibido.

Adicione o seguinte código na sua página (idealmente antes do fechamento da tag </body>):

<!-- 1. Configuração do Chatbot com o Token Seguro -->
<script>
    var carameloaiChatbot = {
        secure_connection_token: "INSIRA_AQUI_O_REAL_TIME_ACCESS_TOKEN",
        project_id: "INSIRA_AQUI_O_PROJECT_ID"
    };
</script>

<!-- 2. Inicialização do SDK (Modo Autenticado) -->
<script src="https://static.carameloai.com/sdk/latest/authenticated.js"></script>

⚠️ Importante: O arquivo carregado no passo 2 é o authenticated.js, que é diferente do index.js usado em fluxos públicos. Não misture os dois.

Exemplo Completo (Node.js / Express)

Aqui está um exemplo simplificado de como seu backend poderia gerar a página:

const PROJECT_ID = "p_xyz123";
const SECRET_TOKEN = process.env.CARAMELO_SECRET_TOKEN;

app.get('/minha-intranet', async (req, res) => {
    // 1. Obtém dados do usuário já logado no seu sistema
    const user = req.user;

    // 2. Chama a API da Caramelo
    const response = await fetch(
        `https://api.carameloai.com/api/chatbox/project/${PROJECT_ID}/intranet-auth`,
        {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                secret_token: SECRET_TOKEN,
                external_customer_id: user.id,
                name: user.name,
                email: user.email
            })
        }
    );

    const data = await response.json();
    const secureToken = data.real_time_access_token;

    // 3. Renderiza o HTML com o token injetado
    res.send(`
        <html>
        <head><title>Minha Intranet</title></head>
        <body>
            <h1>Bem-vindo, ${user.name}</h1>

            <!-- Injeção do token gerado no backend -->
            <script>
                var carameloaiChatbot = {
                    secure_connection_token: "${secureToken}",
                    project_id: "${PROJECT_ID}"
                };
            </script>
            <script src="https://static.carameloai.com/sdk/latest/authenticated.js"></script>
        </body>
        </html>
    `);
});

Dúvidas Frequentes