Chat Autenticado (Intranet)

O que é

O Chat Autenticado (Intranet) é uma forma de publicar o agente dentro de uma plataforma em que os usuários já estão logados, como uma intranet, uma área do cliente, um sistema web ou um ERP.

O chat reconhece automaticamente quem é o usuário, sem pedir login de novo, 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. Criando a conexão

1. Entre no projeto, clique em Robôs Agentes de IA no menu lateral e abra o agente.
2. Clique na aba Canais.
3. Clique em Adicionar canal. Se o agente ainda não tem nenhuma conexão, a lista de canais já aparece direto.
4. No grupo Web, escolha Web autenticada (intranet) e clique em Selecionar.
5. Em Destino e acesso, clique em Continuar. A plataforma avisa que uma conexão de intranet será criada.
6. Em Configuração, preencha:
   • Nome da conexão: um nome interno para você reconhecer depois, como “Portal do Cliente”;
   • Domínios permitidos (opcional): os sites em que o chat pode rodar, um por linha.
7. Clique em Criar conexão.

Na tela “Conexão criada”, clique em Gerenciar conexão e instruções completas. Diferente dos outros modos, a intranet não tem um código pronto para colar: as credenciais e os exemplos ficam na página da conexão.

⚠️ Atenção: criar a conexão não publica uma versão do agente. Enquanto nenhuma versão for publicada, o chat atende com o rascunho atual. Veja como publicar em Seu Primeiro Agente.

3. O que a plataforma mostra na conexão

Para voltar à conexão depois, abra a aba Canais, encontre a conexão em Suas conexões e clique em Gerenciar.

3.1 Exemplos de código

Em Instalação, escolha o que copiar:

• Backend (seu servidor): a chamada que o seu servidor faz para autenticar cada usuário;
• Frontend (navegador): o código que abre o chat na página com o token devolvido pelo seu backend.

Os dois já vêm com o Project ID do seu projeto. Eles correspondem ao Modo A de integração. Existem duas formas de colocar o chat na sua plataforma, explicadas na seção 5.

3.2 Segredo da integração

Em Credenciais e ações, o bloco Segredo da integração (intranet) guarda a chave secreta da conexão. É ela que o servidor da sua plataforma usa para autenticar os usuários no chat. O segredo fica oculto: clique em Revelar segredo para ver e copiar, e em Ocultar quando terminar. Nos exemplos de código, ele aparece como SEU_SECRET_TOKEN.

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

4. Como tudo se conecta

┌─────────────────────┐   1. usuário logado    ┌──────────────────────┐
│  Usuário na sua     │ ─────────────────────▶ │  Backend da sua      │
│  plataforma         │                        │  plataforma          │
└─────────────────────┘                        └──────────┬───────────┘
                                                          │ 2. POST /intranet-auth
                                                          │    (segredo + 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 segredo da integração 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: gere o token a cada carregamento de página, porque ele expira em 24 horas. Não reutilize tokens antigos nem compartilhe o 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 o mesmo script (sdk/latest/client.js) e a mesma chamada intranet-auth no backend. O que muda é como o token chega até o 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/SEU_PROJECT_ID/intranet-auth \
  -H "Authorization: Bearer SEU_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:

<!-- Caramelo AI chatbot (intranet) -->
<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  window.CarameloChatbot
    .create({
      secure_connection_token: 'TOKEN_RETORNADO_PELO_SEU_BACKEND',
      project_id: 'SEU_PROJECT_ID'
    })
    .start();
</script>

O script carrega e abre o chat automaticamente, já identificado.

📌 Já instalou com o código antigo? O formato anterior, com var carameloaiChatbot e o script prod/index.js, continua funcionando.

5.2 Modo B: sob demanda (async)

┌──────────────────┐  1. abre a página   ┌───────────────────────────┐
│  Usuário logado  │ ──────────────────▶ │  Página carrega client.js │
└──────────────────┘                     │  (nada aparece ainda)     │
                                         └────────────┬──────────────┘
                                                      │ 2. chat.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, como /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): crie o chat apontando para o seu endpoint, com autoStart: false, e inicie quando quiser:

<script src="https://static.carameloai.com/sdk/latest/client.js"></script>
<script>
  var chat = window.CarameloChatbot.create(
    {
      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);
      }
    },
    { autoStart: false }
  );

  // O chat só abre quando você mandar, por exemplo ao clicar num botão:
  document.getElementById('abrir-chat').addEventListener('click', function () {
    chat.start();
  });
</script>

Se você já usa o formato antigo, com var carameloaiChatbot e CarameloChatbotClient.start(), ele continua funcionando.

6. Ajustando a aparência

Em Gerenciar, as seções Configurações e Avançado têm as mesmas opções do Chat Público: posição do balão, modo compacto, manter chat aberto, container fixo, temporização e domínios permitidos. Veja o que cada uma faz no guia do Chat Público. Clique em Salvar depois de mudar.

7. Perguntas frequentes