¿Cómo añadir un chat con tecnología de Claude a un sitio de Webflow sin exponer tu clave API?

"¿Cómo añado un chatbot de Claude a mi sitio de Webflow que realmente use mi propia API?" La mayoría de las respuestas apuntan a integraciones de terceros, automatizaciones con Zapier o scripts del lado del cliente que incluyen la clave API directamente en el código. Esos métodos sacrifican la flexibilidad o crean un agujero de seguridad.

Con Webflow Cloud, existe una ruta lista para producción que no requiere un backend independiente, un segundo dominio ni ninguna configuración CORS. Creas una aplicación Next.js o Astro que se ejecuta bajo tu dominio de Webflow existente, generas una ruta del lado del servidor que actúe como proxy de la API de Claude y montas la interfaz de chat en una ruta como mysite.webflow.io/chat.

La clave API permanece en el servidor. Tus visitantes obtienen una interfaz de conversación real.

Esta guía recorre los cinco pasos, desde la configuración de la CLI hasta un chat en vivo montado bajo tu dominio de Webflow, incluyendo los fallos exactos que atrapan a la mayoría de los desarrolladores tras su primer despliegue.

Pruébalo con la IA de Webflow

Este es un caso ideal para que la IA lo construya de principio a fin. Pega el siguiente prompt en Claude Code, Cursor o cualquier herramienta de IA conectada al servidor MCP de Webflow:

Construye una interfaz de chat impulsada por IA en mi sitio de Webflow. El chat debe:

• Renderizarse como un botón flotante en la esquina inferior derecha que abra un panel de chat al hacer clic
• Aceptar mensajes de usuario y transmitir respuestas desde /api/chat (POST { message, history })
• Renderizar formato markdown en las respuestas (negritas, bloques de código, enlaces)
• Preservar el historial de la conversación dentro de la sesión del navegador
• Coincidir con las variables de diseño existentes de mi sitio (color, fuente, espaciado)

Utilizar la API de Webflow Designer para la creación del DOM y la API de datos de Webflow para cualquier configuración persistente.

Reemplaza /api/chat con tu propio endpoint (OpenAI, Anthropic o una función de Webflow Cloud).

Explora más en la biblioteca de comandos de Webflow →

¿Qué necesitas para construir una interfaz de chat de Claude en Webflow?

Necesitas cuatro cosas: un sitio de Webflow con un plan de pago, una clave API de Anthropic, una cuenta de GitHub con Node.js 20+ instalado y conocimientos básicos de React. La configuración de Webflow Cloud maneja la mayor parte de la infraestructura automáticamente. La construcción en sí consiste en una ruta de API de Next.js y un componente de React.

Aquí tienes lo que cubre cada requisito y dónde es importante durante la construcción.

Un sitio de Webflow en cualquier plan de pago

Webflow Cloud está disponible en todos los planes de pago de sitios de Webflow. No lo encontrarás en el plan gratuito Starter. La pestaña Cloud aparece en la Configuración del sitio una vez que tienes un plan de pago, y es ahí donde conectas GitHub, configuras tu proyecto y defines la ruta de montaje que asigna tu aplicación a una URL bajo tu dominio.

Algo que siempre verifico antes de empezar es confirmar que el sitio se haya publicado al menos una vez. Los entornos de Webflow Cloud no se activan hasta que el sitio de Webflow se publica. He visto configuraciones donde el proyecto de Cloud estaba bien, pero el chat no aparecía; la solución era simplemente hacer clic en Publicar en el sitio de Webflow.

Una clave de API de Anthropic

Obtén tu clave de API en console.anthropic.com.

El valor de la clave comienza con sk-ant- y solo se muestra una vez, así que cópialo de inmediato en un gestor de contraseñas o en una nota segura. Si la pierdes, tendrás que generar una nueva y actualizar todos los entornos que la utilicen.

Hay un par de cosas que suelen confundir a la gente aquí. Primero, Anthropic tiene espacios de trabajo separados para diferentes equipos y cuentas de facturación; asegúrate de que la clave pertenezca al espacio de trabajo que quieres facturar.

Segundo, revisa tus límites de uso en la consola antes de lanzar el sitio. Las cuentas nuevas comienzan con límites de tasa que pueden ralentizar un chat muy activo. Tercero, nunca subas la clave a un repositorio de git. Usa .env.local localmente y la configuración de variables de entorno de Webflow Cloud para producción.

He tenido que revocar y regenerar claves para clientes que las subieron a un repositorio público de GitHub antes de terminar la configuración de Cloud.

Una cuenta de GitHub y Node.js 20+

Webflow Cloud admite dos rutas de despliegue:

• Conectar un repositorio de GitHub (para que cada push a la rama conectada active una compilación automáticamente)
• Desplegar manualmente desde tu máquina local usando la CLI

Para esta guía, usaremos la ruta de GitHub porque elimina el paso de despliegue manual tras la configuración inicial. Pero si vas a seguir los pasos sin un repositorio, el despliegue mediante CLI en el Paso 5 funciona igual de bien.

Para Node.js, Node.js 20.0.0 es la versión mínima requerida para la CLI de Webflow y el proyecto Next.js base. Si tienes una versión anterior, la instalación de la CLI se completará, pero el proyecto dará errores durante npm install. Ejecuta node --version antes de empezar. Si tienes una versión inferior a la 20, actualiza con nvm install 20 si usas nvm, o descárgala directamente desde nodejs.org.

Conocimientos básicos de React y TypeScript

La interfaz del chat es un componente cliente de React. No necesitas conocimientos avanzados de TypeScript; los tipos en esta guía son lo suficientemente sencillos como para seguirlos y adaptarlos. Lo que más importa es entender el hookuseState de React y cómo las llamadas fetch asíncronas interactúan con las actualizaciones de estado.

El error más común en las implementaciones de chat con Claude es un fallo en la gestión del estado que provoca que el historial de la conversación se envíe incorrectamente. Entender por qué el código usa una variable local en lugar de la variable de estado directamente (explicado en el Paso 3) te ahorrará una hora de depuración.

5 pasos para crear una interfaz de chat con Claude en Webflow

La construcción se divide claramente en cinco pasos: crear el proyecto de Webflow Cloud, escribir la ruta del proxy del lado del servidor, crear el componente de chat de React, gestionar el contexto de la conversación de varios turnos, y desplegar y montar el chat en tu sitio de Webflow.

Los cinco pasos dan como resultado una interfaz de chat funcional y lista para producción que mantiene tu clave de API segura y el estado de la conversación intacto entre turnos.

Aquí tienes la construcción completa, desde la configuración de la CLI hasta un chat en vivo en tu dominio.

1. Configura tu proyecto de Webflow Cloud

Ve a tu terminal e instala la CLI de Webflow de forma global:

npm install -g @webflow/webflow-cli

Verifica que la instalación se haya completado con webflow --version.

Luego, dirígete a la carpeta donde quieras crear el proyecto y ejecuta:

webflow cloud init

La CLI te guiará a través de cuatro pasos. Selecciona Next.js como tu framework. Introduce /chat como la ruta de montaje. Esta es la ruta URL bajo la cual se ejecutará tu aplicación en tu dominio de Webflow, así que mysite.webflow.io/chat. Autentícate con Webflow cuando se te solicite (se abrirá una ventana del navegador para pedirte que autorices la CLI).

Por último, selecciona tu sitio de Webflow para importar tu sistema de diseño mediante DevLink.

Cuando finalice la inicialización, tendrás un proyecto Next.js estructurado en tu carpeta actual con webflow.json configurado. Sube este proyecto a un nuevo repositorio de GitHub.

Configura y conecta GitHub

En el Diseñador de Webflow, ve a la Configuración del sitio y selecciona Webflow Cloud en la barra lateral. Haz clic en "Log in to GitHub", luego en "Install GitHub" y sigue las instrucciones de autorización.

Una vez conectado, haz clic en Crear nuevo proyecto, introduce un nombre y la URL de tu repositorio de GitHub, y haz clic en Crear proyecto. En la siguiente pantalla, haz clic en Crear entorno, establece la rama (normalmente main), configura la ruta de montaje en /chat, y haz clic en Crear entorno.

Haz clic en Publicar en la esquina superior derecha del Panel de control de Webflow para activar el entorno. El chat aún no será visible (el proyecto Next.js no se ha desplegado), pero el entorno ya está listo para el paso 5.

2. Crea la ruta de la API de Claude en el lado del servidor

Dentro de tu proyecto Next.js, crea el archivo app/api/chat/route.ts. Este archivo actúa como proxy entre tus visitantes y la API de Anthropic. Con la aplicación montada en /chat, esta ruta se resuelve en mysite.webflow.io/chat/api/chat en el sitio activo.

El gestor de rutas completo:

import { NextRequest, NextResponse } from 'next/server';

export const runtime = 'edge';

type Message = {
  role: 'user' | 'assistant';
  content: string;
};

export async function POST(request: NextRequest) {
  const { messages }: { messages: Message[] } = await request.json();

  const apiKey = process.env.ANTHROPIC_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: 'Server configuration error' },
      { status: 500 }
    );
  }

  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'anthropic-version': '2023-06-01',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-6',
      max_tokens: 1024,
      system: 'You are a helpful assistant on this website. Keep responses concise and friendly.',
      messages,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    return NextResponse.json({ error }, { status: response.status });
  }

  const data = await response.json();
  return NextResponse.json(data);
}

Hay tres decisiones en este código que vale la pena entender antes de desplegar:

(1) Primero, export const runtime = 'edge' es obligatorio. Webflow Cloud se ejecuta en Cloudflare Workers, no en Node.js. Si omites esta declaración, la compilación tendrá éxito, pero la ruta fallará durante la ejecución porque se está evaluando en el entorno incorrecto.

El entorno de ejecución en el borde (edge runtime) utiliza la API Fetch y Web Streams. Nada de fs, nada de path, nada de Buffer. He visto compilaciones que pasan, solo para mostrar este error después de la primera solicitud real.

(2) Segundo, el campo system controla lo que sabe el asistente y cómo se comporta. Aquí es donde el chat deja de ser genérico y se vuelve tuyo. Define el producto que respalda, el tono que utiliza, qué preguntas debe responder y qué debe redirigir.

Un mensaje del sistema genérico produce un asistente genérico.

(3) Tercero, model: 'claude-sonnet' es el valor predeterminado ideal para interfaces conversacionales. Equilibra bien la calidad de la respuesta y la velocidad. Para preguntas frecuentes ligeras donde cada milisegundo cuenta, claude-haiku es más rápido y notablemente más económico.

Para flujos de soporte técnico avanzado donde el asistente necesita razonar problemas de varios pasos, claude-opus es la mejora.

3. Almacena tu clave API como una variable de entorno

La clave API nunca debe aparecer en el código fuente. Guárdala en dos lugares: localmente en .env.local, y en producción a través de la configuración de entorno de Webflow Cloud.

Para el desarrollo local, crea .env.local en la raíz del proyecto:

ANTHROPIC_API_KEY=sk-ant-...

Este archivo es ignorado automáticamente por git si utilizas el .gitignore estándar de la estructura de Webflow CLI. Confirma que aparece en .gitignore antes de tu primer push. He visto claves subidas en el commit inicial porque .env.local aún no estaba excluido.

Para producción, ve a Site Settings > Webflow Cloud, abre tu entorno y añade:

• Nombre: ANTHROPIC_API_KEY
• Valor: tu clave API completa

Los nombres de las variables distinguen entre mayúsculas y minúsculas. Si el código de la ruta lee process.env.ANTHROPIC_API_KEY, pero la guardaste como anthropic_api_key en la configuración del entorno, la verificación de la clave fallará con un Server configuration error cada vez.

Prueba la ruta localmente antes de construir la interfaz:

npm install
npm run dev

En una terminal independiente:

curl -X POST http://localhost:3000/chat/api/chat \
  -H "content-type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello, what can you help me with?"}]}'

Una ruta que funciona devuelve una respuesta JSON. La respuesta de Claude está en data.content[0].text. Si ves un error 500, la variable de entorno no se está cargando. Verifica que .env.local exista en la raíz del proyecto (no en una subcarpeta) y que el nombre del archivo coincida exactamente.

4. Construye el componente de interfaz de chat

Reemplaza app/page.tsx con el componente de chat. Este gestiona la entrada del usuario, renderiza la conversación y controla el ciclo de fetch para cada intercambio de mensajes.

'use client';
import { useState, useRef, useEffect } from 'react';

type Message = {
  role: 'user' | 'assistant';
  content: string;
};

export default function ChatPage() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState('');
  const [loading, setLoading] = useState(false);
  const bottomRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
  }, [messages]);

  async function sendMessage() {
    if (!input.trim() || loading) return;

    const userMessage: Message = { role: 'user', content: input };
    const updatedMessages = [...messages, userMessage];

    setMessages(updatedMessages);
    setInput('');
    setLoading(true);

    try {
      const response = await fetch('/chat/api/chat', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ messages: updatedMessages }),
      });

      const data = await response.json();
      if (!response.ok) throw new Error(data.error?.message || 'Request failed');

      setMessages([
        ...updatedMessages,
        { role: 'assistant', content: data.content[0].text },
      ]);
    } catch {
      setMessages([
        ...updatedMessages,
        { role: 'assistant', content: 'Something went wrong. Please try again.' },
      ]);
    } finally {
      setLoading(false);
    }
  }

  return (
    <main style={{ maxWidth: '640px', margin: '0 auto', padding: '2rem' }}>
      <h1>Chat with us</h1>
      <div style={{ minHeight: '400px', border: '1px solid #e0e0e0', borderRadius: '12px', padding: '1rem', marginBottom: '1rem', overflowY: 'auto' }}>
        {messages.map((msg, i) => (
          <div key={i} style={{ marginBottom: '1rem', textAlign: msg.role === 'user' ? 'right' : 'left' }}>
            <span style={{ background: msg.role === 'user' ? '#0066ff' : '#f4f4f4', color: msg.role === 'user' ? '#fff' : '#111', padding: '0.5rem 1rem', borderRadius: '16px', display: 'inline-block', maxWidth: '80%' }}>
              {msg.content}
            </span>
          </div>
        ))}
        {loading && (
          <div style={{ textAlign: 'left' }}>
            <span style={{ background: '#f4f4f4', padding: '0.5rem 1rem', borderRadius: '16px', display: 'inline-block' }}>
              Thinking...
            </span>
          </div>
        )}
        <div ref={bottomRef} />
      </div>
      <div style={{ display: 'flex', gap: '0.5rem' }}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && sendMessage()}
          placeholder="Type a message..."
          style={{ flex: 1, padding: '0.75rem 1rem', borderRadius: '8px', border: '1px solid #e0e0e0', fontSize: '1rem' }}
        />
        <button
          onClick={sendMessage}
          disabled={loading}
          style={{ padding: '0.75rem 1.5rem', background: '#0066ff', color: '#fff', border: 'none', borderRadius: '8px', cursor: loading ? 'not-allowed' : 'pointer', opacity: loading ? 0.6 : 1 }}
        >
          Send
        </button>
      </div>
    </main>
  );
}

El componente gestiona tres estados: messages (el historial completo de la conversación), input (el valor actual del campo de texto) y loading (un booleano que desactiva el botón de enviar mientras hay una solicitud en curso). El useEffect vinculado a messages desplaza la conversación automáticamente hasta el último mensaje.

El destino del fetch es /chat/api/chat; la ruta completa incluyendo el prefijo de montaje. Las rutas dentro de la aplicación deben hacer referencia a la ruta de montaje directamente, no a una ruta relativa desde la página. Usar solo /api/chat se resolvería en mysite.webflow.io/api/chat, que no existe. La ruta completa con el prefijo /chat asegura que la solicitud llegue a la ruta correcta.

Los estilos en línea son solo un punto de partida. Para producción, DevLink te permite llevar tus tokens de diseño de Webflow (fuentes, colores, espaciado) directamente al componente de React. La interfaz de chat puede coincidir con tu marca de Webflow sin necesidad de mantener dos sistemas de estilos paralelos.

5. Despliega y monta el chat en tu sitio de Webflow

Vale la pena entender el contexto de una conversación de varios turnos antes de publicar, ya que el modo de fallo es invisible al principio. La API de mensajes de Claude es completamente sin estado. Cada llamada es independiente y no tiene memoria de sesión.

Para mantener una conversación, cada solicitud debe incluir el historial completo como una matriz de objetos alternos role / content :

[
  { "role": "user", "content": "What plans do you offer?" },
  { "role": "assistant", "content": "We have Starter, Growth, and Enterprise plans..." },
  { "role": "user", "content": "What's in the Growth plan?" }
]

El componente maneja esto construyendo updatedMessages (una nueva matriz que incluye el mensaje actual añadido a todos los mensajes anteriores) y pasándolo tanto a setMessages como al cuerpo del fetch. Este es un detalle crítico.

El error de contexto más común que corrijo en las revisiones de código es que el cuerpo de la petición (fetch body) utiliza messages (la variable de estado) en lugar de updatedMessages (la variable local). Las actualizaciones de estado en React son asíncronas. Dentro de sendMessage, messages siguen siendo la instantánea anterior cuando se dispara la petición. updatedMessages es el array correcto porque se construyó de forma síncrona antes de que se llamara a la actualización de estado.

Conversaciones largas

En las conversaciones largas, los costes de tokens se acumulan. Cada token del historial se factura en cada solicitud. Limitar el historial a los últimos 10 mensajes es una medida de seguridad práctica: sustituye messages: updatedMessages por messages: updatedMessages.slice(-10) en el cuerpo de la petición.

Para sesiones persistentes que deban sobrevivir a las actualizaciones de página, escribe el historial de la conversación en el almacén KV de Webflow Cloud.

Prueba antes de desplegar

Una vez que el componente esté probado localmente, despliégalo en Webflow Cloud.

Primero, autentícate:

webflow auth login

Luego despliega:

webflow cloud deploy

Tras el primer despliegue manual, los siguientes se activarán automáticamente con cada push a tu rama de GitHub conectada. Espera hasta dos minutos para que la compilación y el despliegue se completen. Una vez que esté activo, visita mysite.webflow.io/chat para confirmar que el chat funciona.

Cómo ver el chat en tu sitio de Webflow

Para mostrar el chat en tu sitio principal de Webflow, añade un botón o un elemento de navegación en el Webflow Designer y establece su URL en /chat. Para los equipos que prefieran que el chat esté disponible como una superposición en lugar de en una página separada, añade un elemento de código incrustado de Webflow y carga el chat en un <iframe> que apunte a mysite.webflow.io/chat.

Esto mantiene la aplicación React aislada del lienzo de Webflow y evita conflictos de estilo con los estilos existentes en la página.

¿Qué hace que las interfaces de chat basadas en Claude en Webflow fallen?

La mayoría de los fallos se deben a cuatro causas principales: una variable de entorno inexistente o mal nombrada, una clave API no válida, una llamada a la API de Node.js en el entorno de ejecución edge, o un error de sincronización del estado de React que provoca que se pierda el historial de la conversación. Los síntomas de cada uno son lo suficientemente distintos como para diagnosticarlos rápidamente una vez que sabes qué buscar.

Aquí te explico cómo se manifiesta cada uno y cómo solucionarlo.

Error de configuración del servidor en el primer mensaje

La ruta devuelve un 500, y el cuerpo de la respuesta contiene "Server configuration error". Este es el primer error que veo en casi todas las configuraciones nuevas. Significa que la variable de entorno ANTHROPIC_API_KEY no se está leyendo. O bien no existe, o el nombre en el código no coincide con el nombre en la configuración del entorno.

En el desarrollo local, confirma que .env.local existe en la raíz del proyecto (no en una subcarpeta como src/ o app/) y que contiene exactamente la cadena ANTHROPIC_API_KEY=sk-ant-... sin espacios ni comillas adicionales.

En producción, abre Site Settings > Webflow Cloud, haz clic en tu entorno y lee el nombre de la variable carácter por carácter. Los nombres de las variables de entorno distinguen entre mayúsculas y minúsculas. Una discrepancia como ANTHROPIC_API_KEY frente a anthropic_api_key produce exactamente este error.

Después de actualizar el valor en Webflow Cloud, activa un nuevo despliegue. Los cambios en las variables de entorno no se aplican al despliegue en ejecución; surten efecto en la siguiente compilación.

Error de autenticación 401 de Anthropic

La ruta llega a la API de Anthropic pero es rechazada. La respuesta de error JSON de Anthropic contendrá "type": "authentication_error". Esto significa que el valor de la clave API existe pero no es válido. Ha sido revocada, pertenece a otro espacio de trabajo o se copió incorrectamente.

Ve a console.anthropic.com, revisa la sección de claves API y confirma que la clave esté activa y en la lista. Si se eliminó o caducó, genera una nueva. Copia la cadena completa de la clave. Comienza con sk-ant- y suele tener más de 90 caracteres.

Pégala primero en un editor de texto sin formato para verificar que no incluya saltos de línea ni espacios adicionales. Luego, actualiza el valor en .env.local y en la configuración del entorno de Webflow Cloud, y vuelve a desplegar. También he visto este error cuando un cliente tenía varias cuentas de Anthropic y pegó una clave de su cuenta personal en lugar de la cuenta de facturación que pretendía usar.

La ruta funciona localmente, pero devuelve un error 500 tras desplegar en Webflow Cloud

Este es el error del entorno de ejecución en el borde (edge runtime) y es el que más sorprende a los desarrolladores porque todo parecía ir bien localmente. Webflow Cloud se ejecuta en Cloudflare Workers, que utiliza un entorno de ejecución diferente al de Node.js. El npm run dev local se ejecuta en Node.js, donde los módulos nativos funcionan sin problemas. La versión desplegada se ejecuta en el borde, donde no funcionan.

Las dos causas más comunes son:

• Falta export const runtime = 'edge' al principio del archivo de ruta
• Una dependencia de npm que importa internamente un módulo nativo de Node.js como fs, path, Buffer o crypto

Añade export const runtime = 'edge' si falta. Para problemas con dependencias, revisa los registros de compilación en el panel de despliegue de Webflow Cloud. El error indicará el módulo específico que falló. Sustituye cualquier utilidad específica de Node.js por equivalentes de Fetch API o Web Crypto.

Claude pierde el contexto de la conversación después de unos pocos turnos

El asistente comienza a responder como si no recordara los mensajes anteriores. Ignora lo que se dijo hace dos turnos, contradice su respuesta anterior o responde al último mensaje sin conciencia del contexto. Este error es sutil porque la interfaz de chat parece funcionar bien. El problema está en los datos que se envían.

La causa es casi siempre el error de sincronización de estado descrito en el Paso 5: el cuerpo de la petición (fetch body) está pasando messages (la variable de estado de React, que es la instantánea anterior) en lugar de updatedMessages (la matriz construida localmente que incluye el mensaje actual).

Lee la función sendMessage y confirma que la llamada fetch utiliza updatedMessages en el cuerpo. Si has refactorizado el componente y movido el fetch a una función separada, asegúrate de que updatedMessages se pase como argumento en lugar de volver a leerlo del estado dentro de la función.

He depurado este problema específico en al menos una docena de revisiones de código. La solución siempre es un nombre de variable.

Qué construir a continuación con tu chat de Claude en Webflow

Un chat funcional en tu sitio de Webflow es solo el comienzo. Lo que sabe, cómo persiste y a qué datos puede acceder es lo que lo hace útil para tus visitantes, más allá de una simple demostración. Los siguientes patrones son los pasos naturales para los equipos que quieren pasar de un "chat funcional" a un "chat valioso".

Explora Webflow + Claude para profundizar en la API de Anthropic y en lo que puedes construir en un sitio de Webflow con Claude.