Holagram: un chat en tu web que te llega a Telegram

Holagram es una librería para añadir a tu web un chat de contacto que te llega a Telegram. El visitante se identifica, confirma su email con un enlace de un solo uso y, desde ese momento, cada mensaje que escribe te llega al móvil. Respondes desde Telegram y tu respuesta aparece en su chat, solo en el suyo.

Es lo que usa el botón Let's talk de esta web. En el post Cómo añadir a tu web un chat que te llega a Telegram conté cómo lo construí a mano; Holagram lo empaqueta para que no tengas que escribirlo.

El problema

Un formulario de contacto te llega como un email más, y la conversación se va a otra bandeja. Un chat en vivo (Intercom, Crisp…) obliga a tener una app abierta, una cuota mensual y un panel más que vigilar.

Lo que yo quería era más simple: que la gente me escriba desde la web y yo conteste desde donde ya estoy, Telegram, sin que nadie pueda hacerse pasar por otro y sin montar servidores de WebSockets.

Cómo funciona

1. El visitante abre el chat y se identifica con su nombre y su email.
2. Elige una opción. Las informativas (tarifas, proyectos…) se responden ahí mismo, sin molestarte.
3. Si elige una que requiere hablar contigo, recibe un correo con un enlace de un solo uso (Resend). Caduca a los 30 minutos.
4. Al abrirlo vuelve a tu web, el chat confirma el email y solo entonces se abre la conversación: te llega a Telegram una ficha con su nombre, email y motivo.
5. Cada mensaje suyo te llega a Telegram. Respondes (reply) a su mensaje y tu respuesta aparece en su chat en segundos.

La pieza que lo hace funcionar es pequeña: cada mensaje que el servidor te envía a Telegram guarda en Upstash Redis message_id → conversación. Cuando respondes, Telegram dice a qué mensaje respondiste, y esa es la conversación. Un solo bot, un chat privado contigo y nada de grupos.

Qué necesitas

Tres servicios, los tres con plan gratuito:

Holagram habla con los tres con fetch, así que el paquete no tiene dependencias.

Instalación

pnpm add @angelitolm/holagram

El widget necesita React 18 o 19. El servidor es un handler Request → Response estándar: funciona en los route handlers de Next.js y en cualquier runtime con la misma API (Hono, Remix, Bun…).

Configura el bot con la CLI

Crea el bot con @BotFather (/newbot), ábrelo en Telegram y pulsa Start: un bot no puede escribirte primero. Después, la CLI de Holagram hace el resto:

npx holagram chat-id   # tu chat id, para TELEGRAM_CHAT_ID
npx holagram secret    # un secreto aleatorio para el webhook

Con eso ya tienes las variables de entorno:

TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_CHAT_ID=123456789
TELEGRAM_WEBHOOK_SECRET=...
KV_REST_API_URL=https://xxx.upstash.io
KV_REST_API_TOKEN=...
RESEND_API_KEY=re_...
HOLAGRAM_EMAIL_FROM="Ana <chat@tudominio.com>"

En Vercel, conectar Upstash Redis al proyecto crea KV_REST_API_URL y KV_REST_API_TOKEN automáticamente.

El servidor: una sola ruta

import { createHolagram } from '@angelitolm/holagram/server'
 
export const { GET, POST } = createHolagram({ ownerName: 'Ana' })

Esa ruta atiende todo: pedir la verificación, verificar el enlace, enviar y leer mensajes, y el webhook de Telegram. Si falta alguna variable, responde 503 con los nombres de las que faltan (nunca sus valores), así que lo diagnosticas desde la pestaña de red del navegador.

Tras desplegar, registra el webhook una sola vez:

npx holagram webhook https://tudominio.com

El widget

import { Holagram } from '@angelitolm/holagram'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="es">
      <body>
        {children}
        <Holagram
          owner={{ name: 'Ana', avatar: '/yo.jpg', status: 'Suelo responder en unas horas' }}
          topics={[
            { id: 'hire', label: '💼 Quiero contratarte', intro: 'Cuéntame qué necesitas, plazos y presupuesto.' },
            { id: 'question', label: '💬 Otra pregunta' },
            { id: 'rates', label: '💲 Tarifas', reply: 'Trabajo por horas desde 25 $/h.', links: [{ href: '/servicios', label: 'Servicios' }] },
          ]}
        />
      </body>
    </html>
  )
}

Cada opción es un botón. Las que llevan reply se contestan en el propio chat y nunca te llegan; las demás abren la conversación contigo por Telegram tras verificar el email.

El widget vive en un shadow root: el CSS de tu página no lo rompe y el suyo no se escapa. La conversación se guarda en el localStorage del visitante, así que sobrevive a recargas y se sincroniza entre pestañas (por ejemplo, con la que abrió el enlace del correo).

Hazlo tuyo

• En español: import { Holagram, es } from '@angelitolm/holagram' y text={es}. O cambia solo los textos que quieras con text.
• Tus colores: son variables CSS, [data-holagram] { --hg-from: #a855f7; --hg-to: #3b82f6 }.
• Tu propio botón: openHolagram() abre el chat desde cualquier sitio (un "Hablemos" en el navbar) y closeHolagram() lo cierra. Con launcher="started" el botón flotante solo aparece cuando ya hay una conversación.
• Tu propio lanzador: launcherIcon pone tu avatar o un icono en lugar del bot, y launcherStyle le da estilos.
• Que el visitante lo oculte: con dismissible aparece una pequeña × en el botón.
• Eventos: onLoad, onShow, onClose y onDismiss, por ejemplo para tu analítica.

Seguridad

• La conversación solo existe después de abrir el enlace del correo: desde el navegador no hay forma de saltarse la verificación.
• Redis guarda solo el hash del token, y GETDEL lo consume: el enlace funciona una vez.
• El dominio del enlace es fijo, nunca el Host de la petición, para que nadie pueda mandar a otra persona un enlace válido hacia otro dominio.
• El webhook exige el secreto de Telegram y solo lee tu chat.
• Los mensajes llegan a Telegram como texto plano: el visitante no puede inyectar formato ni enlaces.
• Límites de uso por IP, por email y por conversación, y todo caduca a los 30 días.

Conclusiones

Holagram convierte Telegram en la bandeja de entrada de tu web: verificas a quien te escribe, contestas desde el móvil y cada respuesta llega solo a quien debe, sin servidores propios ni cuotas.

Pruébalo en el botón Let's talk de esta web o, sin instalar nada, en la demo en vivo. La documentación explica cada paso y el código está en GitHub.