La forma correcta de añadir el chat en vivo de Crisp a una aplicación de Webflow Cloud

Webflow Cloud ejecuta tu aplicación como un Cloudflare Worker, y ese simple hecho determina cómo añadir Crisp. El chat en sí es un script del lado del cliente que solo se ejecuta en el navegador, por lo que nunca interactúa directamente con el entorno de ejecución del edge.

Las partes que sí interactúan con el edge son las que hacen que el chat sea útil: saber quién es el usuario que ha iniciado sesión y demostrar esa identidad a Crisp para que tu equipo de soporte pueda confiar en ella.

La configuración se divide en dos partes. La primera es el widget: instala el crisp-sdk-web paquete, móntalo en un Client Component y cárgalo desde tu diseño raíz. La segunda es la personalización: pasa el correo electrónico, el plan y los eventos del usuario conectado a Crisp, y luego firma ese correo electrónico en el lado del servidor para que aparezca verificado en tu bandeja de entrada en lugar de como un visitante anónimo.

En esta guía, construiremos ambas partes en seis pasos, empezando con un chat funcional y terminando con un widget verificado y personalizado que controlas desde tu propio código.

¿Qué necesitas para añadir el chat en vivo de Crisp a una aplicación de Webflow Cloud?

Necesitas una aplicación Next.js en Webflow Cloud y una cuenta de Crisp. El plan gratuito de Crisp cubre el widget y los datos básicos del usuario, y la verificación de identidad criptográfica requiere un plan de pago de Crisp (Mini o superior).

Aquí tienes la lista completa de requisitos:

• Un proyecto de Webflow Cloud ejecutando una aplicación Next.js, ya sea desplegada o en desarrollo local
• Una cuenta de Crisp con un espacio de trabajo (app.crisp.chat)
• Tu ID de sitio web de Crisp (desde la configuración del espacio de trabajo)
• Un plan Crisp Mini o superior, solo si deseas una identidad verificada (la marca de verificación verde)
• Node.js 22.13.0 o superior localmente, el requisito mínimo establecido por Webflow CLI 2.x

El widget en sí toma unos cinco minutos: un paquete y un Client Component. La firma de identidad añade un único Route Handler. Si ya tienes la autenticación configurada, por ejemplo, a través de autenticación Auth0 en un sitio de Webflow, los campos de correo electrónico y usuario que pasas a Crisp son los mismos que ya tienes en el servidor.

6 pasos para añadir el chat en vivo de Crisp a una aplicación de Webflow Cloud

El patrón va desde el widget más sencillo posible hasta uno totalmente personalizado. Los pasos del uno al tres colocan un chat funcional en la página. Los pasos del cuatro al seis identifican al visitante, firman esa identidad en el edge y ponen el control del widget en manos de tu propio código.

Esta es la secuencia que sigo en cada proyecto de Webflow Cloud que incluye un widget de chat.

1. Crea un espacio de trabajo en Crisp y copia tu ID de sitio web

Cada integración de Crisp está vinculada a un ID de sitio web, una cadena corta que le indica al chat qué espacio de trabajo debe cargar. Créalo primero, porque nada más funcionará sin él.

Inicia sesión en app.crisp.chat y crea un espacio de trabajo si aún no tienes uno. Luego, ve a Ajustes > Ajustes del espacio de trabajo > Configuración e integraciones y busca el campo ID del sitio web. Copia el valor.

El ID del sitio web no es un secreto. Se envía al navegador en cada página que carga el chat, por lo que cualquiera puede leerlo en tu paquete de cliente, y esto es así por diseño. Trátalo como un identificador público en lugar de una clave de API.

Esta distinción es importante más adelante, porque cambia la forma en que almacenas cada valor: el ID público del sitio web es seguro para exponerlo al navegador a través de una NEXT_PUBLIC_ variable de entorno. Al mismo tiempo, la clave de firma secreta del paso cinco debe permanecer en el lado del servidor. Ten a mano el ID del sitio web para el siguiente paso.

2. Instala el SDK web de Crisp y crea un componente de cliente

El chat debe cargarse solo en el navegador. En una aplicación de Next.js en Webflow Cloud, esto significa usar un componente de cliente, porque los componentes de servidor y el entorno de ejecución edge no tienen un window objeto al cual Crisp pueda conectarse.

Desde la raíz de tu proyecto de Webflow Cloud, instala el paquete oficial:

npm install crisp-sdk-web

El crisp-sdk-web paquete envuelve el $crisp SDK de JavaScript subyacente de Crisp y añade definiciones de TypeScript, para que obtengas autocompletado en lugar de comandos de cadena sin procesar. Es la configuración que Crisp documenta para aplicaciones de React, Vue y Angular.

Luego crea app/components/CrispChat.tsx como un componente de cliente:

// app/components/CrispChat.tsx
"use client";

import { useEffect } from "react";
import { Crisp } from "crisp-sdk-web";

export default function CrispChat() {
  useEffect(() => {
    // The NEXT_PUBLIC_ prefix exposes the public Website ID to the browser.
    Crisp.configure(process.env.NEXT_PUBLIC_CRISP_WEBSITE_ID!);
  }, []);

  return null;
}

La "use client" directiva es la pieza clave aquí. Le indica a Next.js que renderice este componente en el navegador, donde Crisp.configure() puede ejecutarse. El useEffect hook retrasa la llamada hasta después de que el componente se monte, por lo que nunca se ejecuta durante el renderizado del servidor.

El componente devuelve null porque Crisp inyecta su propio marcado para el chat, sin dejar nada para que React lo renderice. Configura NEXT_PUBLIC_CRISP_WEBSITE_ID en tus variables de entorno de Webflow Cloud, donde el prefijo NEXT_PUBLIC_ es lo que hace que el valor sea legible desde el navegador.

3. Carga Crisp desde tu diseño raíz de Webflow Cloud

Un chat debe seguir al usuario por cada página, así que debe ir en el diseño (layout) y no en una ruta específica. Cargarlo una vez en la raíz significa que persiste durante la navegación del lado del cliente en lugar de recargarse en cada página.

Importa el componente en app/layout.tsx:

// app/layout.tsx
import CrispChat from "./components/CrispChat";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CrispChat />
        {children}
      </body>
    </html>
  );
}

Colocar <CrispChat /> dentro de <body> y por encima de {children} mantiene el widget montado durante toda la sesión. Como es un componente de cliente dentro de un diseño de componente de servidor, Next.js renderiza el esqueleto de la página en el edge e hidrata solo el chat en el navegador.

Despliega esto, abre tu aplicación en su ruta de montaje y la burbuja de Crisp aparecerá en la esquina. En este punto, ya tienes un widget funcional que interactúa con visitantes anónimos.

4. Identifica a los usuarios registrados y envía datos de sesión y eventos

Un chat anónimo es una oportunidad perdida. En el momento en que un usuario inicia sesión, puedes entregarle a Crisp su correo, nombre, plan y comportamiento, para que tu equipo vea contexto en lugar de un perfil vacío. Aquí es donde el chat empieza a valer la pena.

Pasa el usuario autenticado al componente y establece los campos dentro del mismo efecto:

// app/components/CrispChat.tsx
"use client";

import { useEffect } from "react";
import { Crisp } from "crisp-sdk-web";

type Props = {
  user?: { id: string; email: string; name: string; plan: string };
};

export default function CrispChat({ user }: Props) {
  useEffect(() => {
    Crisp.configure(process.env.NEXT_PUBLIC_CRISP_WEBSITE_ID!);

    if (user) {
      Crisp.user.setEmail(user.email);
      Crisp.user.setNickname(user.name);
      Crisp.session.setData({ user_id: user.id, plan: user.plan });
      Crisp.session.pushEvent("app_opened");
    }
  }, [user]);

  return null;
}

Los Crisp.user métodos completan la tarjeta de contacto que ven tus operadores. La Crisp.session.setData() llamada adjunta campos personalizados que puedes filtrar y buscar, como el plan del usuario, y Crisp.session.pushEvent() registra un evento en la línea de tiempo que puedes usar para activar campañas automatizadas o escenarios de bots.

Pasa la user propiedad desde un padre que ya tenga la sesión, y cada conversación llegará prellenada. Lo único que esto no hace es verificar que el correo sea real, lo cual es el siguiente paso.

5. Firma el correo electrónico del usuario en el servidor con Web Crypto

Cualquiera puede llamar a con cualquier dirección, por lo que un correo electrónico sin firma es solo una declaración. La verificación de identidad soluciona esto: firmas el correo con una clave secreta que solo tu servidor y Crisp conocen, y Crisp muestra una insignia de verificado cuando la firma es correcta.Crisp.user.setEmail()

La firma debe realizarse en el servidor y en el entorno de ejecución edge de Webflow Cloud, lo que significa usar Web Crypto.

Primero, obtén tu clave secreta.

En Crisp, ve a Settings > Workspace Settings > Advanced configuration, desplázate hasta Identity Verification y activa "Verify user emails with cryptographic signatures". Copia la clave generada.

Guárdala en Webflow Cloud como una variable de entorno: abre el panel de despliegues (Deployments Dashboard) de tu entorno, haz clic en Environment Variables, elige Add variable > Add single variable, asígnale el nombre , pega el valor y márcala como Secret para que permanezca cifrada y oculta.CRISP_SECRET_KEY

Luego, crea un Route Handler que firme el correo electrónico:

// app/api/crisp/sign/route.ts
import { NextResponse, type NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  const { email } = (await request.json()) as { email: string };

  // Read the secret at runtime from Webflow Cloud's environment.
  const secret = process.env.CRISP_SECRET_KEY as string;
  // Import the key and sign with HMAC-SHA256 using the Web Crypto API.
  const key = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );

  const signed = await crypto.subtle.sign(
    "HMAC",
    key,
    new TextEncoder().encode(email)
  );

  // Crisp expects the signature as a hex string.
  const signature = Array.from(new Uint8Array(signed))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  return NextResponse.json({ signature });
}

Este controlador lee el secreto dentro del cuerpo de la función en lugar de en el nivel superior del módulo, por lo que el valor se resuelve dentro del contexto de la solicitud. Webflow Cloud pone a disposición los Secrets y variables de entorno durante la compilación y en la aplicación desplegada en tiempo de ejecución.

Lee el valor dentro del controlador en lugar de en el nivel superior del módulo, que es el patrón que Webflow documenta para acceder a la configuración en tiempo de ejecución. Los enlaces de almacenamiento como KV o SQLite se acceden por separado a través de . Firma el correo electrónico con , la implementación de Web Crypto que Webflow Cloud enumera como el reemplazo nativo para el edge del de Node.getCloudflareContext()crypto.subtlecrypto

El resultado se convierte al resumen hexadecimal que espera Crisp. Crisp requiere específicamente HMAC-SHA256 y rechaza cualquier otro resumen, lo cual garantiza la opción .hash: "SHA-256"

6. Configura el correo electrónico verificado en el chat y controla el widget

Con la firma proveniente de tu controlador edge, el último paso cierra el círculo: obtén la firma, configura el correo electrónico con ella y la conversación aparecerá como verificada. A partir de ahí, puedes controlar el widget desde tu propia interfaz.

En el componente del cliente, solicita la firma y pásala como segundo argumento a :setEmail

// Inside the useEffect, when a user is present:
(async () => {
    const res = await fetch(`${baseUrl}/api/crisp/sign`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email: user.email }),
  });

  const { signature } = await res.json();

  // The second argument is the HMAC signature from your Route Handler.
  Crisp.user.setEmail(user.email, signature);

  // Open the chatbox from your own button, for example.
  Crisp.chat.open();
})();

El prefijo es importante en Webflow Cloud porque tu aplicación está montada en una ruta base como , por lo que un sin prefijo se resolvería en la raíz incorrecta. Constrúyelo a partir de en tu en lugar de escribirlo directamente en el código.baseUrl/app/api/crisp/signconfig.basePathnext.config.js

Pasar la firma a es lo que activa la marca de verificación verde en tu bandeja de entrada de Crisp. Métodos como , y te permiten conectar el widget a tus propios botones, de modo que un enlace de "Habla con nosotros" en tu navegación abra el chat en lugar de depender solo de la burbuja predeterminada.setEmailCrisp.chat.open()Crisp.chat.show()Crisp.chat.hide()

¿Qué hace que el chat en vivo de Crisp falle en Webflow Cloud?

La mayoría de los problemas de Crisp en Webflow Cloud se deben a una de estas cuatro causas:

• El widget se carga en el servidor en lugar de en el navegador
• El ID del sitio web se lee desde el lugar incorrecto
• Una firma que no coincide
• Un Route Handler que intenta acceder a una API de Node.js que el entorno de ejecución edge no permite utilizar

Cada uno falla de una forma que no señala directamente la causa.

Aquí te explico cómo reconocer cada uno y qué cambiar.

El chat nunca aparece o la compilación falla con el error "window is not defined"

Crisp se está importando o configurando fuera del navegador. Si se ejecuta en un Server Component, en el nivel superior de un módulo o en cualquier ruta de código que se ejecute durante el renderizado del servidor, no hay al que el SDK pueda conectarse, y la compilación o la solicitud fallan.Crisp.configure()window

Mantén todas las llamadas a Crisp dentro de un Client Component marcado con , y llama a dentro de un para que solo se ejecute después de que el componente se monte en el navegador. El componente debe devolver . Este es el error más común al añadir cualquier script exclusivo para navegador a una aplicación Next.js en el edge."use client"Crisp.configure()useEffectnull

El ID del sitio web aparece como undefined en el navegador

A la variable le falta el prefijo o no se configuró para el entorno desplegado. Next.js solo expone al código del lado del cliente las variables que comienzan con . Por lo tanto, una variable llamada permanece solo en el servidor y se lee como dentro de tu Client Component, dejando a sin nada que cargar.NEXT_PUBLIC_NEXT_PUBLIC_CRISP_WEBSITE_IDundefinedCrisp.configure()

Cambia el nombre de la variable a y confirma que esté configurada en el panel de variables de entorno de tu entorno, no solo en un archivo local. Como el ID del sitio web es público, no es necesario marcarlo como secreto.NEXT_PUBLIC_CRISP_WEBSITE_ID.env

Vuelve a desplegar después de realizar el cambio, ya que un nuevo despliegue es lo que detecta las variables de entorno actualizadas.

Todas las conversaciones aparecen como No verificadas en la bandeja de entrada de Crisp

La firma no coincide. Crisp es estricto con el algoritmo y la entrada, por lo que un correo electrónico verificado se convierte en No verificado si firmas con el resumen incorrecto, firmas una cadena diferente a la que configuraste para el correo o usas una clave que no coincide con la de tu espacio de trabajo.

Confirma que firmas la cadena exacta del correo electrónico con HMAC-SHA256 y devuelves un resumen hexadecimal, luego pasa ese resumen como segundo argumento a . Comprueba que coincida con la clave en la configuración avanzada. La verificación también requiere un plan de pago de Crisp, así que confirma que el espacio de trabajo esté en el plan Mini o superior.Crisp.user.setEmail()CRISP_SECRET_KEY

El Route Handler de firma falla o devuelve un error 500 tras el despliegue

El controlador está utilizando un patrón criptográfico de Node.js que el entorno de ejecución de Workers no admite correctamente. El ejemplo de Crisp utiliza de Node, y aunque Webflow Cloud permite la compatibilidad con Node.js, la documentación recomienda explícitamente usar para el hashing y la firma.crypto.createHmaccrypto.subtle

Cambia el controlador a la Web Crypto API como se muestra en el paso cinco: seguido de .crypto.subtle.importKeycrypto.subtle.sign

Lee el secreto desde dentro del controlador en lugar de hacerlo en la parte superior del módulo, para que se resuelva dentro del contexto de la solicitud.process.env

Si quieres detectar errores de controlador como estos en producción, el seguimiento de errores de Sentry en una aplicación de Webflow Cloud muestra el seguimiento de la pila.

Extiende el chat en vivo de Crisp por toda tu aplicación de Webflow Cloud

La configuración de esta guía te proporciona un chat verificado e identificado gestionado desde el edge. A partir de ahí, las extensiones naturales mueven la lógica del navegador a tus Route Handlers y hacia las API de backend de Crisp.

La primera extensión en la mayoría de los proyectos es la mensajería de servidor a servidor. En lugar de solo reaccionar a los visitantes, tu aplicación de Webflow Cloud puede iniciar conversaciones, enviar mensajes y crear contactos a través de la API REST de Crisp cuando ocurre algo en el servidor, como un pedido, una factura o la finalización de una prueba.

Ese trabajo de backend combina a la perfección con la capa de datos detrás de un panel de control en tiempo real usando Supabase en Webflow Cloud, y sigue el mismo patrón que una aplicación full-stack más grande en Webflow Cloud.

Si quieres profundizar en las respuestas automatizadas impulsadas por IA, una interfaz de chat con IA en un sitio de Webflow con Claude demuestra el patrón de proxy del lado del servidor, lo que mantiene las claves de tu modelo fuera del cliente.

Explora Webflow + Crisp para ver el desglose completo de las opciones de instalación, desde un código incrustado en una página estática de Webflow hasta flujos de trabajo basados en API que sincronizan los envíos de formularios con los contactos de Crisp.