Incorporar o AnnA Chat

O AnnA Chat é um gateway de chat web para a plataforma AnnA. Ele fornece uma interface de chat protegida e baseada em navegador, conectando os usuários à plataforma AnnA por meio de operações REST e comunicação via WebSocket.

O acesso é sempre por uma URL gerada pelo seu backend. Esta página cobre a incorporação em um site; para o que o chat faz depois de aberto, veja AnnA Chat.

Qual modo escolher

Modo	Quem é o usuário	O que o backend precisa	Quando usar
Anônimo	Identificador gerado pela AnnA	Nada além de chamar `REST/AnnAChat/Anonymous`	Pontos de entrada públicos, visitantes sem cadastro
Corporativo V2	Usuário corporativo da empresa	Hash da empresa e chaves de criptografia 3DES	Ambientes que ainda não migraram para a V3
Corporativo V3	Usuário corporativo da empresa	Hash da empresa e credenciais para `REST/Credentials/GetToken`	Integrações novas com usuário autenticado

A V3 usa token de curta duração em vez de chaves de criptografia e é a opção recomendada para integrações novas. Em qualquer um dos três modos, o navegador recebe apenas a URL final.

Incorporar com acesso anônimo

É possível incorporar o AnnA Chat ao site do cliente usando um iframe dentro de um botão flutuante. O site do cliente controla quando a janela do chat é aberta, enquanto o AnnA Chat é carregado pela URL fornecida pelo seu backend.

Antes de começar

Você pode definir ANNA_URL no exemplo usando uma URL gerada pelo seu backend ou uma URL montada com os parâmetros descritos abaixo.

Opção 1: URL gerada pelo backend

Gere a URL do chat anônimo no seu backend e substitua ANNA_CHAT_URL no exemplo pela URL retornada por REST/AnnAChat/Anonymous.

Opção 2: URL com idioma e serviço inicial

Você também pode montar a URL diretamente usando dois parâmetros posicionais e sem nome:

https://YOUR_ANNA_ENVIRONMENT_URL/annachatanonimo.aspx?LANGUAGE,@startService

LANGUAGE deve ser POR para português brasileiro, SPA para espanhol ou ENG para inglês.
startService é o segundo parâmetro e deve sempre começar com @.
Os parâmetros são separados por uma vírgula e não possuem nomes.

Por exemplo, substitua LANGUAGE e startService por POR e @YOUR_START_SERVICE:

https://YOUR_ANNA_ENVIRONMENT_URL/annachatanonimo.aspx?POR,@YOUR_START_SERVICE

Use a URL completa como o valor de ANNA_URL no exemplo HTML.

Exemplo completo

O exemplo a seguir cria um botão no canto inferior direito da página. Ao clicar no botão, a janela do chat é aberta ou fechada.

<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Exemplo de AnnA Chat incorporado</title>
  </head>
  <body>
    <h1>Site do cliente corporativo</h1>
    <p>O widget do AnnA Chat aparece no canto inferior direito.</p>

    <script>
      (function () {
        const ANNA_URL = "ANNA_CHAT_URL"; // Substitua por uma URL gerada pelo backend ou pelo formato de URL direta descrito acima
        const CHAT_W = 400,
          CHAT_H = 600,
          BTN_SIZE = 60;
        const sideOffset = "clamp(16px, 2.2vw, 30px)";
        const bottomOffset = "clamp(16px, 2.2vw, 30px)";

        const btn = document.createElement("div");
        btn.id = "anna-launcher";
        Object.assign(btn.style, {
          position: "fixed",
          bottom: bottomOffset,
          right: sideOffset,
          width: BTN_SIZE + "px",
          height: BTN_SIZE + "px",
          borderRadius: "50%",
          cursor: "pointer",
          zIndex: "9999",
          background: "#7c3aed",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          boxShadow: "0 4px 12px rgba(0,0,0,0.25)",
          transition: "transform 0.2s",
        });
        btn.innerHTML =
          '<svg width="28" height="28" fill="#fff" viewBox="0 0 24 24"><path d="M20 2H4a2 2 0 0 0-2 2v18l4-4h14a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2z"/></svg>';
        btn.onmouseenter = function () {
          btn.style.transform = "scale(1.1)";
        };
        btn.onmouseleave = function () {
          btn.style.transform = "scale(1)";
        };

        const chat = document.createElement("div");
        chat.id = "anna-chat";
        Object.assign(chat.style, {
          position: "fixed",
          bottom: `calc(${bottomOffset} + ${BTN_SIZE}px + 10px)`,
          right: sideOffset,
          width: `min(${CHAT_W}px, calc(100vw - 32px))`,
          height: CHAT_H + "px",
          maxHeight: `min(${CHAT_H}px, calc(100vh - 116px))`,
          borderRadius: "12px",
          overflow: "hidden",
          boxShadow: "0 8px 30px rgba(0,0,0,0.3)",
          display: "none",
          zIndex: "9998",
        });
        chat.innerHTML =
          '<iframe src="' +
          ANNA_URL +
          '" style="width:100%;height:100%;border:none" allow="camera *; microphone *; geolocation *"></iframe>';

        btn.addEventListener("click", function () {
          var open = chat.style.display === "none";
          chat.style.display = open ? "block" : "none";
        });

        document.body.appendChild(chat);
        document.body.appendChild(btn);
      })();
    </script>
  </body>
</html>

Como funciona

ANNA_URL é a URL do AnnA Chat carregada pelo iframe.
O botão e a janela do chat são criados dinamicamente, então a página precisa apenas do script e de um local para incluí-lo.
A janela do chat começa oculta com display: none.
Ao clicar no botão, a janela do chat alterna entre os estados oculto e visível.
O iframe usa a URL de ANNA_URL e preenche a janela do chat.

Ajustando as dimensões

Altere CHAT_W, CHAT_H e BTN_SIZE para ajustar a largura do chat, a altura do chat e o tamanho do botão. As expressões min() e clamp() mantêm o chat e seus espaçamentos dentro da área visível em telas menores.

Gerando a URL do chat no backend

A URL de um chat anônimo incorporado deve ser gerada pelo seu backend chamando diretamente REST/AnnAChat/Anonymous. Esse endpoint não requer uma solicitação separada de credenciais ou token.

Selecione a aba correspondente à linguagem do seu backend. Cada exemplo chama REST/AnnAChat/Anonymous e imprime sua resposta, que contém a URL a ser usada como ANNA_CHAT_URL no exemplo do lado do cliente.

using System.Text;

using var http = new HttpClient
{
  BaseAddress = new Uri("https://YOUR_ANNA_ENVIRONMENT/")
};

var result = await http.PostAsync(
  "REST/AnnAChat/Anonymous",
  new StringContent(
    """
    {
      "language": "POR",
      "startService": ""
    }
    """,
    Encoding.UTF8,
    "application/json"));

result.EnsureSuccessStatusCode();

Console.WriteLine(await result.Content.ReadAsStringAsync());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    var httpClient = HttpClient.newHttpClient();
    var baseUrl = "https://YOUR_ANNA_ENVIRONMENT/";

    var anonymousRequest = HttpRequest.newBuilder()
        .uri(URI.create(baseUrl + "REST/AnnAChat/Anonymous"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString("""
          {
            "language": "POR",
            "startService": ""
          }
          """))
        .build();

    var anonymousResponse = httpClient.send(
        anonymousRequest,
        HttpResponse.BodyHandlers.ofString());

    if (anonymousResponse.statusCode() / 100 != 2) {
      throw new IllegalStateException(
          "AnnA Chat request failed: " + anonymousResponse.body());
    }

    System.out.println(anonymousResponse.body());
  }
}

<?php

function postJson(string $url, array $payload): string
{
    $headers = ["Content-Type: application/json"];

    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
    ]);

    $body = curl_exec($curl);
    if ($body === false) {
        $error = curl_error($curl);
        curl_close($curl);
        throw new RuntimeException($error);
    }

    $statusCode = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    curl_close($curl);

    if ($statusCode < 200 || $statusCode >= 300) {
        throw new RuntimeException("Request failed: " . $body);
    }

    return $body;
}

$baseUrl = "https://YOUR_ANNA_ENVIRONMENT/";

$chatResponse = postJson(
    $baseUrl . "REST/AnnAChat/Anonymous",
    ["language" => "POR", "startService" => ""]
);

  echo $chatResponse . PHP_EOL;

Este exemplo requer a extensão cURL do PHP.

import requests

base_url = "https://YOUR_ANNA_ENVIRONMENT/"

chat_response = requests.post(
    f"{base_url}REST/AnnAChat/Anonymous",
    json={"language": "POR", "startService": ""},
    timeout=30,
)
chat_response.raise_for_status()

print(chat_response.text)

Instale a biblioteca Requests antes de executar o exemplo.

O código imprime a resposta de REST/AnnAChat/Anonymous. Use a URL retornada nessa resposta como o valor de ANNA_CHAT_URL no exemplo de incorporação do lado do cliente.

O valor de language nos exemplos de requisição ao backend é POR, o que abre o chat em português brasileiro. Use SPA para espanhol ou ENG para inglês. O valor de startService está vazio no exemplo de requisição ao backend. Ao usar o formato de URL direta, o parâmetro startService deve sempre começar com @.

Veja também

Requisitos e limites — requisitos de navegador, permissões e limites que afetam o chat incorporado.
Como acessar — o que a pessoa vê quando a URL gerada é aberta.
AnnA Chat — a documentação completa de uso.