Integrar AnnA Chat

AnnA Chat es una puerta de enlace de chat web para la plataforma AnnA. Proporciona una interfaz de chat protegida y basada en navegador, conectando a los usuarios con la plataforma AnnA mediante operaciones REST y comunicación por WebSocket.

El acceso siempre se hace por una URL generada por tu backend. Esta página cubre la integración en un sitio web; para saber qué hace el chat una vez abierto, consulta AnnA Chat.

Qué modo elegir

Modo	Quién es el usuario	Qué necesita el backend	Cuándo usarlo
Anónimo	Identificador generado por AnnA	Nada más que llamar a `REST/AnnAChat/Anonymous`	Puntos de entrada públicos, visitantes sin registro
Corporativo V2	Usuario corporativo de la empresa	Hash de la empresa y claves de cifrado 3DES	Entornos que aún no migraron a la V3
Corporativo V3	Usuario corporativo de la empresa	Hash de la empresa y credenciales para `REST/Credentials/GetToken`	Integraciones nuevas con usuario autenticado

La V3 usa un token de corta duración en lugar de claves de cifrado y es la opción recomendada para integraciones nuevas. En los tres modos el navegador solo recibe la URL final.

Integrar con acceso anónimo

Es posible integrar AnnA Chat en el sitio web del cliente mediante un iframe dentro de un botón flotante. El sitio web del cliente controla cuándo se abre la ventana del chat, mientras que AnnA Chat se carga desde la URL proporcionada por tu backend.

Antes de comenzar

Puedes definir ANNA_URL en el ejemplo utilizando una URL generada por tu backend o una URL construida con los parámetros descritos a continuación.

Opción 1: URL generada por el backend

Genera la URL del chat anónimo en tu backend y reemplaza ANNA_CHAT_URL en el ejemplo por la URL devuelta por REST/AnnAChat/Anonymous.

Opción 2: URL con idioma y servicio inicial

También puedes construir la URL directamente utilizando dos parámetros posicionales y sin nombre:

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

LANGUAGE debe ser POR para portugués brasileño, SPA para español o ENG para inglés.
startService es el segundo parámetro y siempre debe comenzar con @.
Los parámetros están separados por una coma y no tienen nombres.

Por ejemplo, reemplaza LANGUAGE y startService por SPA y @YOUR_START_SERVICE:

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

Usa la URL completa como valor de ANNA_URL en el ejemplo HTML.

Ejemplo completo

El siguiente ejemplo crea un botón en la esquina inferior derecha de la página. Al hacer clic en el botón, la ventana del chat se abre o se cierra.

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Ejemplo de AnnA Chat integrado</title>
  </head>
  <body>
    <h1>Sitio del cliente corporativo</h1>
    <p>El widget de AnnA Chat aparece en la esquina inferior derecha.</p>

    <script>
      (function () {
        const ANNA_URL = "ANNA_CHAT_URL"; // Reemplaza por una URL generada por el backend o por el formato de URL directa descrito arriba
        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>

Cómo funciona

ANNA_URL es la URL de AnnA Chat que carga el iframe.
El botón y la ventana del chat se crean dinámicamente, por lo que la página solo necesita el script y un lugar para incluirlo.
La ventana del chat comienza oculta mediante display: none.
Al hacer clic en el botón, la ventana del chat alterna entre los estados oculto y visible.
El iframe utiliza la URL de ANNA_URL y ocupa toda la ventana del chat.

Ajustar las dimensiones

Cambia CHAT_W, CHAT_H y BTN_SIZE para ajustar el ancho del chat, la altura del chat y el tamaño del botón. Las expresiones min() y clamp() mantienen el chat y sus márgenes dentro del área visible en pantallas pequeñas.

Generar la URL del chat en el backend

La URL de un chat anónimo integrado debe generarse en tu backend llamando directamente a REST/AnnAChat/Anonymous. Este endpoint no requiere una solicitud separada de credenciales o token.

Selecciona la pestaña correspondiente al lenguaje de tu backend. Cada ejemplo llama a REST/AnnAChat/Anonymous e imprime su respuesta, que contiene la URL que debes usar como ANNA_CHAT_URL en el ejemplo del lado del 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": "SPA",
      "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": "SPA",
            "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" => "SPA", "startService" => ""]
);

  echo $chatResponse . PHP_EOL;

Este ejemplo requiere la extensión cURL de PHP.

import requests

base_url = "https://YOUR_ANNA_ENVIRONMENT/"

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

print(chat_response.text)

Instala la biblioteca Requests antes de ejecutar el ejemplo.

El código imprime la respuesta de REST/AnnAChat/Anonymous. Usa la URL devuelta en esa respuesta como valor de ANNA_CHAT_URL en el ejemplo de integración del lado del cliente.

El valor de language en los ejemplos de solicitud al backend es SPA, lo que abre el chat en español. Usa POR para portugués brasileño o ENG para inglés. El valor de startService está vacío en el ejemplo de solicitud al backend. Al utilizar el formato de URL directa, el parámetro startService siempre debe comenzar con @.

Ver también

Requisitos y límites — requisitos del navegador, permisos y límites que afectan al chat integrado.
Cómo acceder — lo que ve la persona cuando se abre la URL generada.
AnnA Chat — la documentación completa de uso.