Con la API, tu web o tu app muestra el contenido de tu centro de ayuda (artículos, FAQs y vídeos) con su propio diseño, y abre conversaciones con tu equipo en nombre de sus usuarios. También sirve para escribir el contenido (como borradores, con imágenes y vídeos) y la descripción del producto que lee el agente IA, por ejemplo con Claude Code.
- URL base:
https://app.helpeen.com/api/v1 - Formato: JSON en peticiones y respuestas, UTF-8.
- Sin SDK: cualquier cliente HTTP vale (
fetch,curl,axios,requests…).
Primeros pasos
- En el panel, entra en Integración y crea una clave pública (
hp_pub_…). - Pide todo el contenido de tu centro de ayuda en una llamada:
curl https://app.helpeen.com/api/v1/help \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
- Pinta la respuesta con tu diseño. Si además quieres que tus usuarios escriban al equipo, crea una
clave secreta (
hp_sec_…) y llama a/conversationsdesde tu servidor.
¿Prefieres no programar? Con el widget añades un chat flotante o un centro de ayuda completo con una línea de HTML.
Widget
Tres formas de poner Helpeen en una web sin llamar a la API:
| Qué añade | Cómo | |
|---|---|---|
| Chat flotante | Un botón que abre un panel para escribir al equipo y seguir las respuestas | Una línea <script> |
| Centro de ayuda | Un bloque dentro de la página con buscador, FAQs, artículos, vídeos y formulario de contacto | Un <div> y la misma línea |
| React | Los dos anteriores como componentes | npm install @helpeen/react |
El aspecto (color, posición, estilo del botón, tema y textos) se configura en el panel, en Widget, y llega a las webs que ya lo tienen sin tocar su código. Todo se sirve en iframes desde Helpeen, así que no choca con los estilos de tu web. Usa tu clave pública.
Chat flotante
Pega esta línea antes de </body> (o en el <head>):
<script src="https://app.helpeen.com/widget.js" data-key="hp_pub_xxxxxxxxxxxxxxxx" async></script>
El panel solo se descarga la primera vez que alguien pulsa el botón, así que no ralentiza la carga.
Centro de ayuda incrustado
Pon el <div> donde quieras que aparezca. Con data-launcher="off" no sale el botón flotante:
<div data-helpeen="help"></div>
<script src="https://app.helpeen.com/widget.js" data-key="hp_pub_xxxxxxxxxxxxxxxx" data-launcher="off" async></script>
Se ajusta en alto a su contenido. Puedes poner varios <div data-helpeen="help"> en la misma página.
React
npm install @helpeen/react
import { HelpeenChat, HelpeenHelpCenter } from "@helpeen/react";
// Chat flotante, una vez, en tu layout:
<HelpeenChat publicKey="hp_pub_xxxxxxxxxxxxxxxx" />
// Centro de ayuda, en tu página de ayuda:
<HelpeenHelpCenter publicKey="hp_pub_xxxxxxxxxxxxxxxx" />
Las dos aceptan locale. HelpeenHelpCenter acepta además className y style para el contenedor.
UI templates
Interfaces de soporte ya hechas para incrustar en tu web, por si no quieres programar la tuya contra la API. Se añaden y se personalizan en Integración › UI templates (colores, esquinas, densidad, fuente, textos, cabecera…), y cada una tiene un id. El componente es el mismo para todas: el id dice cuál es. Hay dos:
- Chat tipo bandeja: la lista de conversaciones del usuario y cada conversación como en tu bandeja, en tarjetas o burbujas.
- Chat estilo WhatsApp: barra de color, fondo con dibujo y burbujas con la hora y los ✓✓ dentro.
Las dos tienen adjuntos y notas de voz.
Ocupa todo su contenedor, así que dale una altura:
<div data-helpeen="template" data-template="ID_DEL_TEMPLATE" style="height:640px"></div>
<script src="https://app.helpeen.com/widget.js" data-key="hp_pub_xxxxxxxxxxxxxxxx" data-launcher="off" async></script>
import { HelpeenTemplate } from "@helpeen/react";
<HelpeenTemplate publicKey="hp_pub_xxxxxxxxxxxxxxxx" template="ID_DEL_TEMPLATE" style={{ height: 640 }} user={helpeenUser} />
Lo que pases en options (o en data-options, en JSON) manda sobre lo guardado en Helpeen, clave a
clave:
<HelpeenTemplate
publicKey="hp_pub_xxxxxxxxxxxxxxxx"
template="ID_DEL_TEMPLATE"
options={{ colors: { accent: "#0a7cff" }, radius: "round", showList: false }}
/>
| Opción | Valores |
|---|---|
colors |
{ accent, background, team, user }, cada uno #rrggbb. El texto encima se pone negro o blanco solo |
layout |
tickets (tarjetas, como la bandeja) o bubbles. El de WhatsApp siempre va en burbujas |
radius |
square, soft o round |
density |
compact o comfortable |
font |
system, grotesk, inter o serif |
fontSize |
sm, md o lg |
title, greeting |
Textos de la cabecera. Vacíos, los del widget en el idioma del usuario |
showHeader, showList |
true o false. Sin lista, el usuario entra directo en su última conversación |
showBranding |
false para quitar «Funciona con helpeen». Solo en planes de pago |
Las sesiones y los usuarios identificados funcionan igual que en el chat flotante (ver abajo).
Atributos del script
| Atributo | ||
|---|---|---|
data-key |
obligatorio | Tu clave pública |
data-locale |
opcional | Idioma, con código de dos letras (fr, pt-BR…). Sin él, el del navegador del visitante (ver «Idioma del widget») |
data-launcher |
opcional | off para no mostrar el botón flotante |
data-user-id, data-user-email, data-user-name, data-user-hash |
opcional | Usuario identificado, ver abajo |
data-user-metadata, data-user-metadata-hash |
opcional | Contexto del usuario identificado (plan, país…) y su firma, ver abajo |
Visitantes y usuarios identificados
Sin hacer nada más, quien escribe desde el widget es un visitante: deja su email, y el widget recuerda sus conversaciones en ese navegador. Las respuestas le llegan también por email.
Si tu web tiene login, puedes identificar al usuario: el widget no le pide el email y le
enseña sus conversaciones, las mismas que abras por la API con su user_id. Para que nadie pueda
hacerse pasar por otro, tu servidor firma el id con el secreto de identidad del panel
(Widget › Usuarios identificados):
// En tu servidor (Node.js). Nunca en el navegador.
import { createHmac } from "node:crypto";
const userHash = createHmac("sha256", process.env.HELPEEN_IDENTITY_SECRET).update(user.id).digest("hex");
Y se lo pasas al widget:
<script src="https://app.helpeen.com/widget.js" data-key="hp_pub_xxxxxxxxxxxxxxxx"
data-user-id="u_123" data-user-email="ana@ejemplo.com" data-user-name="Ana"
data-user-hash="9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" async></script>
<HelpeenChat publicKey="hp_pub_xxxxxxxxxxxxxxxx" user={{ id: "u_123", email: "ana@ejemplo.com", name: "Ana", hash: userHash }} />
Si la firma no es válida, el usuario entra como visitante. Si regeneras el secreto, todos los usuarios identificados pasan a visitantes hasta que tu servidor firme con el nuevo.
Contexto del usuario
A un usuario identificado puedes añadirle lo que sabes de él (plan, país, número de proyectos…).
Se guarda en el metadata de cada conversación que abra desde el widget, y lo ven tu equipo y el
agente de IA. Es un objeto JSON en texto, firmado aparte con el mismo secreto: HMAC-SHA256 del
id, un salto de línea y el JSON tal cual lo envías.
// En tu servidor, junto a userHash.
const userMetadata = JSON.stringify({ plan: "pro", country: "ES" });
const userMetadataHash = createHmac("sha256", process.env.HELPEEN_IDENTITY_SECRET)
.update(`${user.id}\n${userMetadata}`)
.digest("hex");
<script src="https://app.helpeen.com/widget.js" data-key="hp_pub_xxxxxxxxxxxxxxxx"
data-user-id="u_123" data-user-email="ana@ejemplo.com" data-user-name="Ana"
data-user-hash="9f86d081…"
data-user-metadata='{"plan":"pro","country":"ES"}'
data-user-metadata-hash="<firma del metadata>" async></script>
<HelpeenChat publicKey="hp_pub_xxxxxxxxxxxxxxxx"
user={{ id: "u_123", email: "ana@ejemplo.com", name: "Ana", hash: userHash, metadata: userMetadata, metadata_hash: userMetadataHash }} />
Hasta 4.000 caracteres. Si la firma no es válida, o no es un objeto JSON, el contexto se descarta
pero el usuario sigue identificado. El que guarda el widget (source, page) va por encima.
Idioma del widget
El widget tiene sus textos en más de 50 idiomas: todos los europeos (también catalán, euskera, gallego, ruso, ucraniano…), árabe, hebreo, hindi, chino, japonés, coreano y más. Elige así:
- El que le pases con
data-locale(o la proplocaleen React), si lo tiene. - Si no, el primero de los idiomas del navegador del visitante que tenga.
- Si no, el idioma por defecto de tu empresa.
El centro de ayuda embebido sigue el mismo idioma: cada artículo llega traducido si tiene esa traducción publicada y, si no, en el idioma por defecto. Los textos personalizados del panel (Widget › Textos) se escriben por idioma; en un idioma sin los tuyos, el widget usa los suyos.
Si tu web deja elegir idioma sin recargar la página, díselo al widget y se recarga en el nuevo:
window.Helpeen("locale", "de"). En React basta con cambiar la prop locale.
Controlarlo desde tu código
window.Helpeen("open"); // abre el chat
window.Helpeen("close");
window.Helpeen("toggle");
window.Helpeen("identify", { id: "u_123", email: "ana@ejemplo.com", name: "Ana", hash: "…" });
// con contexto: añade metadata (el JSON en texto) y metadata_hash
window.Helpeen("logout"); // al cerrar sesión en tu web
window.Helpeen("mount"); // rellena <div data-helpeen="help"> y "template" añadidos después de cargar
window.Helpeen("locale", "fr"); // cambia de idioma sin recargar la página (null: el del navegador)
Las llamadas que hagas antes de que cargue el script se ejecutan al cargar si defines la cola:
window.Helpeen = window.Helpeen || function () { (window.Helpeen.q = window.Helpeen.q || []).push(arguments); };.
Con React, usa helpeen("open"), que importas de @helpeen/react.
Dónde funciona
El widget solo se deja incrustar en los dominios de Ajustes › Orígenes permitidos (en cualquiera si la lista está vacía). Para evitar abusos, cada visitante puede abrir 5 conversaciones por hora y cada empresa recibe como mucho 100 por hora desde el widget.
Para recordar la sesión, el widget guarda un identificador en el almacenamiento local del navegador (dentro del iframe de Helpeen). Es necesario para el servicio que pide el usuario, así que no requiere consentimiento, pero conviene mencionarlo en tu política de cookies.
Autenticación
Todas las peticiones llevan la clave en la cabecera Authorization:
Authorization: Bearer <clave>
| Clave | Prefijo | Qué puede hacer | Dónde se usa |
|---|---|---|---|
| Pública | hp_pub_ |
Leer el contenido publicado | Navegador, app móvil o servidor |
| Secreta | hp_sec_ |
Todo, incluidas las conversaciones, salvo escribir contenido | Solo en tu servidor |
| Editor | hp_edt_ |
Crear y editar borradores de contenido (Edición de contenido) | Solo en un servidor o un terminal |
Reglas:
- La clave secreta nunca va en un navegador ni en una app. Una petición con clave secreta que
lleve cabecera
Origin(es decir, que sale de un navegador) se rechaza con403. Si una clave secreta acaba en una página, revócala en Integración y crea otra. Lo mismo vale para la de editor. - Orígenes permitidos. Con la clave pública desde un navegador, el origen de la página tiene que
estar en Ajustes › Orígenes permitidos (por ejemplo
https://tuapp.com). Si la lista está vacía, se acepta cualquier origen. Las peticiones sinOrigin(servidor, app móvil) no se ven afectadas. - CORS está activado para
GETyPOST, con las cabecerasAuthorizationyContent-Type. - Una clave revocada deja de funcionar al momento (
401).
Convenciones
- Ids: UUID en texto.
- Fechas: ISO 8601 en UTC, por ejemplo
2026-10-01T10:00:00.000Z. - Campos vacíos: un campo opcional sin valor viene como
null, nunca se omite (salvobodyybody_htmlen los listados de artículos, ver abajo). - Orden: el contenido viene en el orden que le has dado en el panel (
position) y, a igualdad, por título. - Solo lo publicado: la API nunca devuelve borradores, salvo en la edición de contenido con una clave de editor.
Idioma
Los endpoints de contenido aceptan ?locale= con un código de dos letras (es, en, fr…). Sin
él, o si no es válido, se usa el idioma por defecto de tu empresa.
Cada artículo y cada FAQ es un único contenido con sus traducciones, y cada traducción se publica
por separado. Al pedir un idioma, cada uno llega en ese idioma si tiene esa traducción publicada y,
si no, en el idioma por defecto de tu empresa: un centro de ayuda a medio traducir sigue mostrándolo
todo. El campo locale de cada resultado dice en qué idioma viene, y locales, en cuáles está
publicado.
Las categorías también tienen nombre por idioma, con la misma regla: la de cada artículo llega en el idioma del artículo. Las colecciones de vídeos, de momento, tienen un único idioma cada una.
Paginación
/articles y /faqs admiten limit (de 1 a 100, 50 por defecto) y offset (desde 0). La
respuesta repite los valores aplicados:
{ "data": [], "limit": 50, "offset": 0 }
Si data trae menos elementos que limit, no hay más páginas.
Errores
Todos los errores tienen la misma forma:
{
"error": {
"code": "not_found",
"message": "No article `conectar-un-banco`."
}
}
code |
HTTP | Cuándo |
|---|---|---|
invalid_request |
400 | Falta un campo, sobra longitud o el cuerpo no es un objeto JSON |
conflict |
409 | Con la clave de editor, el cambio tocaría contenido publicado |
unauthorized |
401 | No hay clave, tiene un formato raro, no existe o está revocada |
forbidden |
403 | Clave sin permiso para el endpoint, clave secreta o de editor desde un navegador, origen no permitido, o un editor que pide publicar |
storage_full |
403 | Tu empresa ha llenado el espacio para archivos de su plan |
not_found |
404 | El artículo, la categoría o la conversación no existen (o no son de ese usuario) |
internal |
500 | Error nuestro. Reintenta más tarde |
message está en inglés y sirve para depurar; no lo enseñes tal cual a tus usuarios.
Contenido
Se puede llamar con la clave pública o con la secreta.
GET /help
Todo lo que necesita una página de soporte, en una sola llamada: las FAQs (con su respuesta, hasta 100) con sus categorías, y las colecciones de vídeos. Las categorías son solo las de FAQs.
| Parámetro | Tipo | |
|---|---|---|
locale |
query, opcional | Idioma del contenido |
curl "https://app.helpeen.com/api/v1/help?locale=es" \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"organization": { "name": "Monestic", "slug": "monestic" },
"locale": "es",
"categories": [
{
"id": "6f1c2a8e-4b0d-4e8a-9a51-2f7d3c9b1e20",
"slug": "bancos",
"name": "Bancos",
"description": "Conectar, sincronizar y desconectar cuentas.",
"kind": "faq",
"position": 0
}
],
"faqs": [
{
"id": "b2e4d6f8-1a3c-4e5f-8a9b-0c1d2e3f4a5b",
"slug": "es-seguro",
"kind": "faq",
"title": "¿Es seguro conectar mi banco?",
"excerpt": null,
"category": { "slug": "bancos", "name": "Bancos" },
"locale": "es",
"locales": ["es"],
"position": 0,
"published_at": "2026-09-12T08:30:00.000Z",
"updated_at": "2026-09-20T16:02:11.000Z",
"body": "Sí. Nunca vemos tus claves: la conexión se hace a través de tu banco.",
"body_html": "<p>Sí. Nunca vemos tus claves: la conexión se hace a través de tu banco.</p>\n"
}
],
"video_collections": [
{
"id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a",
"slug": "primeros-pasos",
"title": "Primeros pasos",
"description": null,
"locale": "es",
"locales": ["en", "es"],
"position": 0,
"videos": [
{
"id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"title": "Conecta tu banco",
"description": "En menos de dos minutos.",
"url": "https://youtu.be/dQw4w9WgXcQ",
"provider": "youtube",
"embed_url": "https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ",
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
"position": 0
}
]
}
]
}
GET /categories
Las categorías, para montar la navegación de tu centro de ayuda. Los artículos y las FAQs tienen
cada uno sus categorías: kind dice de cuáles es cada una.
| Parámetro | Tipo | |
|---|---|---|
kind |
query, opcional | article o faq. Sin él, las de los dos |
locale |
query, opcional | Idioma de los nombres |
curl "https://app.helpeen.com/api/v1/categories?kind=faq&locale=es" \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"data": [
{
"id": "6f1c2a8e-4b0d-4e8a-9a51-2f7d3c9b1e20",
"slug": "bancos",
"name": "Bancos",
"description": "Conectar, sincronizar y desconectar cuentas.",
"kind": "faq",
"position": 0
},
{
"id": "7a2d3b9f-5c1e-4f9b-8b62-3a8e4d0c2f31",
"slug": "facturacion",
"name": "Facturación",
"description": null,
"kind": "faq",
"position": 1
}
]
}
Se devuelven en el orden del panel, con el nombre y la descripción en el idioma pedido
(?locale=) o, si esa traducción no existe, en el idioma por defecto. El slug es el mismo en
todos los idiomas: úsalo para agrupar o filtrar. Es único dentro de cada kind, así que una
categoría de artículos y otra de FAQs pueden compartirlo.
GET /articles
Artículos y FAQs publicados, con filtros y búsqueda.
| Parámetro | Tipo | |
|---|---|---|
kind |
query, opcional | article o faq. Sin él, los dos |
category |
query, opcional | Slug de categoría, del mismo kind. 404 si no existe |
q |
query, opcional | Texto a buscar en título, extracto y cuerpo (hasta 100 caracteres, sin distinguir mayúsculas) |
locale |
query, opcional | Idioma del contenido |
limit, offset |
query, opcional | Paginación |
En el listado, los artículos van sin body ni body_html (pide cada uno con
/articles/{slug}), y las FAQs van con ellos, porque son cortas y se leen en el sitio.
curl "https://app.helpeen.com/api/v1/articles?category=bancos&q=sincroniz&limit=10" \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"data": [
{
"id": "c3f5e7a9-2b4d-4f6a-9b8c-1d2e3f4a5b6c",
"slug": "conectar-un-banco",
"kind": "article",
"title": "Cómo conectar un banco",
"excerpt": "Paso a paso, y qué hacer si la sincronización se para.",
"category": { "slug": "bancos", "name": "Bancos" },
"locale": "es",
"locales": ["es"],
"position": 0,
"published_at": "2026-09-10T09:00:00.000Z",
"updated_at": "2026-09-28T11:45:00.000Z"
}
],
"limit": 10,
"offset": 0
}
GET /articles/{slug}
Un artículo o una FAQ, siempre con body (Markdown) y body_html.
| Parámetro | Tipo | |
|---|---|---|
slug |
ruta | Slug del artículo |
locale |
query, opcional | Idioma. El mismo slug puede existir en varios idiomas |
curl https://app.helpeen.com/api/v1/articles/conectar-un-banco \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"data": {
"id": "c3f5e7a9-2b4d-4f6a-9b8c-1d2e3f4a5b6c",
"slug": "conectar-un-banco",
"kind": "article",
"title": "Cómo conectar un banco",
"excerpt": "Paso a paso, y qué hacer si la sincronización se para.",
"category": { "slug": "bancos", "name": "Bancos" },
"locale": "es",
"locales": ["es"],
"position": 0,
"published_at": "2026-09-10T09:00:00.000Z",
"updated_at": "2026-09-28T11:45:00.000Z",
"body": "## Antes de empezar\n\nTen a mano el acceso a tu banca online.\n\n1. Ve a **Cuentas**.\n2. Pulsa **Añadir banco**.",
"body_html": "<h2>Antes de empezar</h2>\n<p>Ten a mano el acceso a tu banca online.</p>\n<ol>\n<li>Ve a <strong>Cuentas</strong>.</li>\n<li>Pulsa <strong>Añadir banco</strong>.</li>\n</ol>\n"
}
}
404 Not Found si no hay un artículo publicado con ese slug en ese idioma:
{ "error": { "code": "not_found", "message": "No article `conectar-un-banco`." } }
body_html ya viene saneado: el HTML que se hubiera escrito a mano en el Markdown sale
escapado, y los enlaces o imágenes con esquemas peligrosos (javascript:, data:) pierden la URL.
Se puede insertar tal cual (innerHTML, dangerouslySetInnerHTML, v-html).
GET /faqs
Atajo de /articles?kind=faq. Mismos parámetros salvo kind; las FAQs siempre traen su respuesta.
curl "https://app.helpeen.com/api/v1/faqs?category=facturacion" \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"data": [
{
"id": "d4a6b8c0-3e5f-4a7b-8c9d-2e3f4a5b6c7d",
"slug": "cambiar-tarjeta",
"kind": "faq",
"title": "¿Cómo cambio la tarjeta de pago?",
"excerpt": null,
"category": { "slug": "facturacion", "name": "Facturación" },
"locale": "es",
"locales": ["es"],
"position": 0,
"published_at": "2026-09-15T10:00:00.000Z",
"updated_at": "2026-09-15T10:00:00.000Z",
"body": "En **Ajustes › Suscripción**, pulsa *Cambiar tarjeta*.",
"body_html": "<p>En <strong>Ajustes › Suscripción</strong>, pulsa <em>Cambiar tarjeta</em>.</p>\n"
}
],
"limit": 50,
"offset": 0
}
GET /videos
Colecciones de vídeos publicadas, con sus vídeos ordenados. Helpeen no aloja vídeo: guarda el enlace de YouTube o Vimeo y te da la URL para incrustarlo.
Cada colección y cada vídeo llega con el título y la descripción en el idioma pedido o, si no
están traducidos a él, en el idioma por defecto de tu empresa. locale dice el idioma en que
llega la colección y locales, todos los que tiene. Un vídeo puede tener su propia versión en un
idioma (doblada o subtitulada): entonces url, provider, embed_url y thumbnail_url son los
de esa versión; si no, los del vídeo principal.
| Parámetro | Tipo | |
|---|---|---|
locale |
query, opcional | Idioma de los títulos y descripciones |
curl https://app.helpeen.com/api/v1/videos \
-H "Authorization: Bearer hp_pub_xxxxxxxxxxxxxxxx"
200 OK
{
"data": [
{
"id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a",
"slug": "primeros-pasos",
"title": "Primeros pasos",
"description": null,
"locale": "es",
"locales": ["en", "es"],
"position": 0,
"videos": [
{
"id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"title": "Conecta tu banco",
"description": "En menos de dos minutos.",
"url": "https://youtu.be/dQw4w9WgXcQ",
"provider": "youtube",
"embed_url": "https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ",
"thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
"position": 0
},
{
"id": "8b7c6d5e-4f3a-4b2c-1d0e-9f8a7b6c5d4e",
"title": "Exporta tus datos",
"description": null,
"url": "https://vimeo.com/123456789",
"provider": "vimeo",
"embed_url": "https://player.vimeo.com/video/123456789",
"thumbnail_url": null,
"position": 1
}
]
}
]
}
Para incrustarlo: <iframe src="{embed_url}" allowfullscreen></iframe>. thumbnail_url es null
en Vimeo.
Conversaciones
Solo con clave secreta y desde tu servidor (desde el navegador, usa el widget).
Helpeen no tiene cuentas de usuarios finales:
tu app ya sabe quién es su usuario y lo dice con user_id, el id que tenga en tu base de datos
(texto, hasta 200 caracteres). Una conversación solo se puede leer o contestar con el mismo
user_id que la abrió; con cualquier otro, la respuesta es 404.
El user_id tiene que salir de la sesión de tu servidor, nunca de un parámetro que mande el
navegador: si no, cualquiera podría leer las conversaciones de otro usuario.
Estados
| Estado | Significa | Pasa a este estado cuando… |
|---|---|---|
open |
Le toca responder al equipo | El usuario abre la conversación o escribe en ella, aunque estuviera cerrada |
pending |
Le toca al usuario | El equipo responde desde el panel |
closed |
Resuelta | El equipo la cierra desde el panel |
unread es true cuando lo último es una respuesta del equipo y el usuario aún no la ha visto
(no se ha llamado a /read ni ha escrito después). Úsalo para el globo de "tienes respuesta".
Avisos por email
Helpeen los manda solo, no hace falta que lo hagas tú:
- Cuando un usuario abre una conversación o escribe en ella → email al correo de avisos de tu empresa (Ajustes).
- Cuando el equipo responde → email al usuario, a la dirección con la que abrió la conversación.
Si tu empresa tiene un retraso de envío (Ajustes), cada respuesta del equipo espera ese
tiempo antes de salir: hasta entonces no aparece en GET /conversations/{id}, no cuenta para
unread y no se manda el email.
GET /conversations
Las conversaciones de un usuario, la de actividad más reciente primero (hasta 100).
| Parámetro | Tipo | |
|---|---|---|
user_id |
query, obligatorio | Id del usuario en tu app |
curl "https://app.helpeen.com/api/v1/conversations?user_id=u_123" \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx"
200 OK
{
"data": [
{
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"subject": "No me sincroniza el banco",
"status": "pending",
"metadata": { "plan": "optimum", "page": "/bancos" },
"created_at": "2026-10-01T09:12:00.000Z",
"last_message_at": "2026-10-01T10:03:27.000Z",
"unread": true
}
]
}
POST /conversations
Abre una conversación con el primer mensaje del usuario.
| Campo | Tipo | |
|---|---|---|
user.id |
texto, obligatorio | Id del usuario en tu app (hasta 200) |
user.email |
texto, obligatorio | Donde le llegarán las respuestas |
user.name |
texto, opcional | Nombre para el equipo (hasta 120) |
subject |
texto, obligatorio | Asunto (hasta 200) |
message |
texto, opcional | Primer mensaje (hasta 10.000). Obligatorio si no van attachment_ids: una nota de voz puede ir sola |
attachment_ids |
[uuid], opcional | Archivos para el primer mensaje, subidos antes con POST /attachments sin conversation_id |
metadata |
objeto, opcional | Lo que quieras que vea el equipo junto a la conversación: plan, versión de la app, página… (hasta 4 KB) |
curl https://app.helpeen.com/api/v1/conversations \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"user": { "id": "u_123", "email": "ana@ejemplo.com", "name": "Ana" },
"subject": "No me sincroniza el banco",
"message": "Desde ayer no veo movimientos nuevos.",
"metadata": { "plan": "optimum", "page": "/bancos" }
}'
201 Created
{
"data": {
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"subject": "No me sincroniza el banco",
"status": "open",
"metadata": { "plan": "optimum", "page": "/bancos" },
"created_at": "2026-10-01T09:12:00.000Z",
"last_message_at": "2026-10-01T09:12:00.000Z",
"unread": false
}
}
400 Bad Request si falta algo o no cumple los límites:
{ "error": { "code": "invalid_request", "message": "`user.email` is not an email." } }
Guarda el id: lo necesitas para leer la conversación y contestar en ella.
GET /conversations/{id}
Una conversación con todos sus mensajes, del más antiguo al más nuevo.
| Parámetro | Tipo | |
|---|---|---|
id |
ruta | Id de la conversación |
user_id |
query, obligatorio | Tiene que ser el usuario que la abrió |
curl "https://app.helpeen.com/api/v1/conversations/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9?user_id=u_123" \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx"
200 OK
{
"data": {
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"subject": "No me sincroniza el banco",
"status": "pending",
"metadata": { "plan": "optimum", "page": "/bancos" },
"created_at": "2026-10-01T09:12:00.000Z",
"last_message_at": "2026-10-01T10:03:27.000Z",
"unread": true,
"messages": [
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"author": "user",
"author_name": "Ana",
"body": "Desde ayer no veo movimientos nuevos.",
"created_at": "2026-10-01T09:12:00.000Z",
"deleted": false,
"attachments": [
{
"id": "9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
"name": "captura.png",
"content_type": "image/png",
"size": 184320,
"kind": "image",
"url": "https://helpeen-attachments.fsn1.your-objectstorage.com/…",
"download_url": "https://helpeen-attachments.fsn1.your-objectstorage.com/…"
}
]
},
{
"id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"author": "agent",
"author_name": "Iñaki",
"body": "Hola, Ana. Tu banco pidió renovar el permiso: entra en Cuentas y pulsa «Reconectar».",
"created_at": "2026-10-01T10:03:27.000Z",
"deleted": false,
"attachments": []
}
]
}
}
body es texto plano: escápalo al pintarlo y respeta los saltos de línea (por ejemplo con
white-space: pre-wrap). Leer la conversación no la marca como leída: para eso está /read.
Los archivos de cada mensaje van en attachments (ver Attachment). Sus url están
firmadas y caducan: pinta lo que devuelva la última llamada, no las guardes. Un mensaje que el
equipo ha eliminado sigue en su sitio con deleted: true, sin texto ni archivos.
POST /conversations/{id}/messages
El usuario escribe en una conversación. La deja en open (aunque estuviera cerrada), cuenta como
leída y avisa al equipo por email.
| Campo | Tipo | |
|---|---|---|
user_id |
texto, obligatorio | El usuario que la abrió |
body |
texto | El mensaje (hasta 10.000). Puede faltar si lleva archivos |
attachment_ids |
[uuid], opcional | Archivos subidos antes con POST /attachments para esta conversación |
curl https://app.helpeen.com/api/v1/conversations/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9/messages \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "user_id": "u_123", "body": "Gracias, ya funciona." }'
201 Created
{
"data": {
"id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
"author": "user",
"author_name": "Ana",
"body": "Gracias, ya funciona.",
"created_at": "2026-10-01T10:20:41.000Z",
"deleted": false,
"attachments": []
}
}
POST /attachments
Hace sitio para un archivo que el usuario va a enviar y devuelve dónde subirlo. Los archivos no pasan por la API: se suben directamente al almacenamiento, en tres pasos:
POST /attachmentscon lo que es el archivo →idyupload_url.PUTdel archivo aupload_url, conContent-Typeigual alcontent_typeque devuelve. Puedes hacerlo desde tu servidor o desde el navegador del usuario (admite cualquier origen).- Envía el mensaje con
attachment_ids: [id, …]: en una conversación conPOST /conversations/{id}/messages, o en una nueva conPOST /conversations.
| Campo | Tipo | |
|---|---|---|
user_id |
texto, obligatorio | El usuario que lo envía |
name |
texto, obligatorio | Nombre del archivo (hasta 255) |
content_type |
texto, opcional | Tipo MIME, como image/png. Por defecto, application/octet-stream |
size |
entero, obligatorio | Tamaño en bytes |
conversation_id |
uuid, opcional | La conversación donde se enviará. Sin él, es para el primer mensaje de una nueva |
curl https://app.helpeen.com/api/v1/attachments \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "user_id": "u_123", "name": "captura.png", "content_type": "image/png", "size": 184320,
"conversation_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9" }'
201 Created
{
"data": {
"id": "9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
"upload_url": "https://helpeen-attachments.fsn1.your-objectstorage.com/…",
"content_type": "image/png",
"expires_in": 900
}
}
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @captura.png
upload_url caduca a los 15 minutos (expires_in, en segundos). Un archivo subido que no se envía
en un día se borra. Al enviar el mensaje se comprueba que cada archivo está subido y no pasa del
tamaño máximo; si no, 400 y el mensaje no se envía. Lo que ocupan los archivos cuenta en el
espacio de tu empresa: lleno, la respuesta es 403 storage_full.
POST /conversations/{id}/read
Marca como vistas las respuestas del equipo: unread pasa a false. Llámalo cuando el usuario
abra la conversación en tu app.
| Campo | Tipo | |
|---|---|---|
user_id |
texto, obligatorio | El usuario que la abrió |
curl https://app.helpeen.com/api/v1/conversations/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9/read \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "user_id": "u_123" }'
200 OK
{ "data": { "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "unread": false } }
Descripción del producto
Lo que el agente IA sabe de tu producto, tal como lo ven tus usuarios: un Markdown que escribe
Claude Code a partir del código de tu proyecto, con la skill que da el panel en Agente IA ›
Conocimiento. Cada proyecto tiene una sola; subir otra sustituye a la anterior. Se trocea por sus
títulos ##, una entrada de conocimiento por sección. Guardarla no gasta tokens de IA. Con la clave
secreta, desde un servidor o un terminal.
PUT /knowledge/product-brief
El cuerpo es el Markdown tal cual (Content-Type: text/markdown), o JSON { "markdown": "…" }.
Hasta 100.000 caracteres. Solo con el plan Pro, que trae el agente IA (si no, 403).
curl -X PUT https://app.helpeen.com/api/v1/knowledge/product-brief \
-H "Authorization: Bearer hp_sec_xxxxxxxxxxxxxxxx" \
-H "Content-Type: text/markdown; charset=utf-8" \
--data-binary @helpeen-product-brief.md
{ "data": { "sections": 12, "tokens": 8450, "updated_at": "2026-10-19T10:00:00.000Z" } }
Responde 400 si está vacía, pasa del máximo o, sumada al resto del conocimiento, el agente no
podría leerla entera en cada respuesta.
GET /knowledge/product-brief
La descripción actual, con el mismo formato, o "data": null si no hay ninguna.
DELETE /knowledge/product-brief
La quita. Responde "data": null.
Edición de contenido
Con una clave de editor (hp_edt_…), artículos, FAQs, categorías y colecciones de vídeos se
escriben desde fuera del panel. Está pensada para que quien conozca bien el producto redacte el
contenido con Claude Code, con el código delante: en Integración › API Keys el panel ofrece una
skill de Claude Code ya preparada para tu proyecto, que hace todas estas llamadas por ti.
Reglas:
- Todo se guarda como borrador. Pedir
"status": "published"se rechaza con403. Publicar se hace siempre en el panel, por una persona. - Lo publicado no se toca. Una traducción publicada, la categoría y el orden de un artículo con
alguna traducción publicada, una categoría que contiene algo publicado y una colección de vídeos
publicada (y sus vídeos) responden
409 conflict. Se cambian desde el panel. - Se identifica por
slug.PUTcrea el elemento si no existe y lo actualiza si existe, así que repetir una llamada no duplica nada. - Solo desde un servidor o un terminal. Como la secreta, con cabecera
Originse rechaza. - Ve también los borradores. Los
GETde esta sección devuelven todo, con todos los idiomas y el estado de cada uno, yeditabledice qué se puede cambiar con esta clave.
GET /editor
El proyecto de la clave: name, slug, default_locale (su idioma principal), locales (los
idiomas en los que ya hay contenido) y panel_url.
Artículos y FAQs
GET /editor/articles
?kind=article|faq, ?category=<slug>, limit y offset como en /articles.
{
"data": [
{
"id": "1b6c2f0e-8d4a-4c7b-9e21-5a3f7d8c9b10",
"slug": "cambiar-contrasena",
"kind": "faq",
"category": "cuenta",
"position": 0,
"editable": false,
"translations": {
"en": {
"status": "draft",
"editable": true,
"title": "How do I change my password?",
"body": "Go to **Settings › Security**…",
"published_at": null,
"updated_at": "2026-10-12T10:00:00.000Z"
},
"es": {
"status": "published",
"editable": false,
"title": "¿Cómo cambio la contraseña?",
"body": "Ve a **Ajustes › Seguridad**…",
"published_at": "2026-10-10T09:00:00.000Z",
"updated_at": "2026-10-10T09:00:00.000Z"
}
},
"panel_url": "https://app.helpeen.com/o/tu-proyecto/faqs/1b6c2f0e-8d4a-4c7b-9e21-5a3f7d8c9b10"
}
],
"limit": 50,
"offset": 0
}
Los artículos traen además excerpt en cada traducción. GET /editor/articles/{slug} devuelve uno.
PUT /editor/articles/{slug}
Crea el artículo o la FAQ, o guarda uno de sus idiomas, siempre como borrador.
curl -X PUT https://app.helpeen.com/api/v1/editor/articles/cambiar-contrasena \
-H "Authorization: Bearer hp_edt_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"kind": "faq",
"locale": "es",
"category": "cuenta",
"title": "¿Cómo cambio la contraseña?",
"body": "Ve a **Ajustes › Seguridad** y pulsa **Cambiar contraseña**."
}'
| Campo | ||
|---|---|---|
kind |
para crear | article o faq. No cambia después |
locale |
opcional | El idioma que se guarda. Sin él, el principal |
title |
obligatorio | En una FAQ, la pregunta |
body |
obligatorio | Markdown, sin HTML |
excerpt |
opcional | Solo artículos |
category |
opcional | slug de una categoría del mismo kind, o null |
position |
opcional | Orden (0 va primero). Uno nuevo va al final |
category y position son comunes a todos los idiomas: solo cambian mientras ninguno está
publicado. El slug va en minúsculas con guiones (cambiar-contrasena). Responde 201 al crearlo
y 200 al actualizarlo, con el artículo como en GET.
DELETE /editor/articles/{slug}
Con ?locale=xx, borra ese idioma si es un borrador (no si es el único que queda). Sin locale,
borra el artículo entero si no tiene nada publicado.
Imágenes y vídeos
Las imágenes y los vídeos de un artículo se suben al almacenamiento de Helpeen y el body los
enlaza en Markdown, con una URL pública que no caduca. Se suben en dos pasos, como los adjuntos:
POST /editor/media
curl -X POST https://app.helpeen.com/api/v1/editor/media \
-H "Authorization: Bearer hp_edt_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "ajustes.png", "content_type": "image/png", "size": 184320 }'
| Campo | ||
|---|---|---|
name |
obligatorio | El nombre del archivo. Sin la extensión, es el texto alternativo |
content_type |
obligatorio | image/png, image/jpeg, image/gif, image/webp, image/avif, video/mp4, video/webm o video/quicktime |
size |
obligatorio | Tamaño exacto en bytes. Hasta 10 MB las imágenes y 100 MB los vídeos |
Responde 201:
{
"data": {
"id": "6f1c…",
"kind": "image",
"content_type": "image/png",
"size": 184320,
"upload_url": "https://…",
"url": "https://helpeen-public.fsn1.your-objectstorage.com/…/media/6f1c…/ajustes.png",
"markdown": "",
"expires_in": 900
}
}
Después, el archivo se sube con un PUT a upload_url en los 15 minutos siguientes, con el mismo
Content-Type y exactamente size bytes; con otro tipo u otro tamaño el almacenamiento lo rechaza
(403):
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @ajustes.png
markdown va en el body, en una línea propia. Los vídeos se escriben igual () y
se muestran con reproductor. Cada archivo cuenta para el almacenamiento del plan desde que se pide su
upload_url (403 storage_full si no queda); uno que nunca llega a subirse se descuenta al cabo de
una hora. Como mucho 60 subidas por hora con cada clave.
Categorías
Los artículos y las FAQs tienen categorías distintas, así que la ruta lleva el tipo.
GET /editor/categories?kind=article|faq: todas, conslug,kind,position,editableytranslations({ "es": { "name", "description" } }).PUT /editor/categories/{faq|article}/{slug}: la crea o cambia sus nombres y su orden mientras no contenga nada publicado. Elslugva en minúsculas con guiones bajos (cuenta_y_acceso).{ "translations": { "es": { "name": "Cuenta y acceso", "description": "Entrar, contraseñas, cerrar la cuenta" }, "en": { "name": "Account and access" } }, "position": 2 }Una nueva necesita el nombre en el idioma principal. Se guardan los idiomas enviados y los demás se quedan como estaban.
DELETE /editor/categories/{faq|article}/{slug}: mientras no contenga nada publicado. Sus borradores se quedan sin categoría.
Vídeos
Los vídeos son enlaces de YouTube o Vimeo; no se sube nada.
GET /editor/collections: todas las colecciones, constatus,editable,translationsy susvideos(cada uno conid,url,provider,positionytranslations).GET /editor/collections/{slug}devuelve una.PUT /editor/collections/{slug}: la crea como borrador o cambia sus textos y su orden mientras lo sea.{ "translations": { "es": { "title": "Primeros pasos", "description": "…" } }, "position": 0 }. Elslugva en minúsculas con guiones.DELETE /editor/collections/{slug}: una colección en borrador, con sus vídeos.POST /editor/collections/{slug}/videos: añade un vídeo al final (o enposition). Otro idioma puede tener su propia versión del vídeo conurlen su traducción:{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "translations": { "es": { "title": "Tu primera cuenta", "description": "…" }, "en": { "title": "Your first account", "url": "https://youtu.be/abc123XYZ" } } }PUT /editor/videos/{id}: cambiaurl,translationsopositionde un vídeo de una colección en borrador.DELETE /editor/videos/{id}lo quita.
Objetos
Category
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
slug |
texto | Identificador en snake_case (bancos_y_sincronizacion), único entre las de su kind e igual en todos los idiomas |
name |
texto | En el idioma pedido, o en el de por defecto |
description |
texto o null |
Ídem |
kind |
article o faq |
Lo que agrupa: artículos o FAQs |
position |
entero | Orden en el panel |
Article
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
slug |
texto | Único en tu empresa, igual en todos los idiomas |
kind |
article o faq |
En una FAQ, title es la pregunta y body la respuesta |
title |
texto | |
excerpt |
texto o null |
Resumen corto para listados |
category |
{ slug, name } o null |
|
locale |
texto | Idioma en el que viene: el pedido o, si no está traducido, el de por defecto |
locales |
[texto] | Idiomas en los que está publicado |
position |
entero | |
published_at |
fecha | Cuándo se publicó esta traducción |
updated_at |
fecha | |
body |
texto | Markdown. Solo en el detalle y en las FAQs |
body_html |
texto | HTML saneado. Solo en el detalle y en las FAQs |
Collection
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
slug |
texto | |
title |
texto | |
description |
texto o null |
|
locale |
texto | |
position |
entero | |
videos |
[Video] | Ordenados por position |
Video
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
title |
texto | |
description |
texto o null |
|
url |
texto | El enlace original |
provider |
youtube o vimeo |
|
embed_url |
texto | Para un <iframe>. YouTube va en su versión sin cookies |
thumbnail_url |
texto o null |
null en Vimeo |
position |
entero |
Conversation
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
subject |
texto | |
status |
open, pending o closed |
Ver Estados |
metadata |
objeto | El que mandaste al abrirla ({} si ninguno) |
created_at |
fecha | |
last_message_at |
fecha | |
unread |
booleano | Hay respuesta del equipo sin ver |
messages |
[Message] | Solo en GET /conversations/{id} |
Message
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
author |
user o agent |
agent es alguien de tu equipo |
author_name |
texto o null |
|
body |
texto | Texto plano. Vacío si solo lleva archivos o se ha eliminado. Si el equipo traduce sus respuestas, las del equipo llegan ya en el idioma en que escribe el usuario |
created_at |
fecha | Cuándo le llegó al usuario |
deleted |
booleano | El equipo lo eliminó: no tiene texto ni archivos |
attachments |
[Attachment] | Sus archivos |
Attachment
| Campo | Tipo | |
|---|---|---|
id |
uuid | |
name |
texto | Nombre del archivo |
content_type |
texto | Tipo MIME |
size |
entero | Bytes |
kind |
image, video, audio, text o file |
Cómo mostrarlo |
url |
URL | Para verlo: el navegador lo muestra si puede (imágenes, vídeo, audio, PDF, texto) y si no, lo descarga. Caduca en una o dos horas |
download_url |
URL | Lo descarga siempre, con su nombre. Caduca igual |
transcript |
texto, opcional | Solo en las notas de voz del equipo, desde el plan Basic: lo que se dice en el audio, para mostrarlo debajo. Una respuesta traducida no lleva el audio: su texto va traducido en body |
Límites
user_id |
200 caracteres |
user.email |
320 caracteres |
user.name |
120 caracteres |
subject |
200 caracteres |
message, body |
10.000 caracteres |
metadata |
4 KB en JSON |
| Archivo | 25 MB |
| Archivos por mensaje | 10 |
| Archivos subidos sin enviar, por usuario | 20 |
q |
100 caracteres (se recorta) |
limit |
1–100 |
| Conversaciones por usuario en el listado | 100 |
FAQs en /help |
100 |
Edición: title |
200 caracteres |
Edición: body |
50.000 caracteres |
Edición: excerpt, description |
300 caracteres |
| Edición: nombre de categoría | 80 caracteres |
| Edición: título de colección / de vídeo | 120 / 160 caracteres |
| Edición: imagen / vídeo subido | 10 MB / 100 MB |
| Edición: subidas de archivos por clave | 60 por hora |
| Descripción del producto | 100.000 caracteres |
Ejemplo: página de soporte en Next.js
Contenido leído en el servidor y cacheado cinco minutos, y un formulario de contacto que abre la conversación desde una server action:
// lib/helpeen.ts
const HELPEEN = "https://app.helpeen.com/api/v1";
async function helpeen<T>(path: string, init: RequestInit & { next?: { revalidate?: number } } = {}) {
const res = await fetch(`${HELPEEN}${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.HELPEEN_SECRET_KEY}`,
"Content-Type": "application/json",
...init.headers,
},
});
const json = await res.json();
if (!res.ok) throw new Error(`Helpeen ${res.status}: ${json.error?.message}`);
return json as T;
}
export const getHelp = (locale: string) =>
helpeen<HelpResponse>(`/help?locale=${locale}`, { next: { revalidate: 300 } });
export const openConversation = (input: {
user: { id: string; email: string; name?: string };
subject: string;
message: string;
metadata?: Record<string, unknown>;
}) => helpeen<{ data: Conversation }>("/conversations", { method: "POST", body: JSON.stringify(input) });
// app/soporte/actions.ts
"use server";
export async function contact(formData: FormData) {
const user = await requireUser(); // tu sesión: el user_id sale de aquí, no del formulario
await openConversation({
user: { id: user.id, email: user.email, name: user.name },
subject: String(formData.get("subject")),
message: String(formData.get("message")),
metadata: { plan: user.plan },
});
}
Ejemplo: FAQs en una web estática
Con la clave pública, directamente desde el navegador (añade el dominio en Orígenes permitidos):
<div id="faqs"></div>
<script>
// `title` is plain text: escape it. `body_html` is already safe.
const escape = (text) =>
text.replace(/[&<>"']/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[c]);
fetch("https://app.helpeen.com/api/v1/faqs?locale=es", {
headers: { Authorization: "Bearer hp_pub_xxxxxxxxxxxxxxxx" },
})
.then((r) => r.json())
.then(({ data }) => {
document.getElementById("faqs").innerHTML = data
.map((faq) => `<details><summary>${escape(faq.title)}</summary>${faq.body_html}</details>`)
.join("");
});
</script>