Documentación · v1

La API de Helpeen. Sin sorpresas.

Once endpoints, JSON y una clave. Aquí está todo: cómo autenticarte, cada endpoint con su petición y su respuesta, los errores y los límites.

¿Lo implementa una IA?

Dale a Claude, Cursor o tu asistente la guía completa: reglas de seguridad, qué arquitectura elegir, código listo para adaptar y esta referencia entera, en un solo Markdown.

También en /llms.txt y /llms-full.txt, donde los asistentes la buscan solos.

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

  1. En el panel, entra en Integración y crea una clave pública (hp_pub_…).
  2. 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"
  1. 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 /conversations desde 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í:

  1. El que le pases con data-locale (o la prop locale en React), si lo tiene.
  2. Si no, el primero de los idiomas del navegador del visitante que tenga.
  3. 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 con 403. 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 sin Origin (servidor, app móvil) no se ven afectadas.
  • CORS está activado para GET y POST, con las cabeceras Authorization y Content-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 (salvo body y body_html en 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:

  1. POST /attachments con lo que es el archivo → id y upload_url.
  2. PUT del archivo a upload_url, con Content-Type igual al content_type que devuelve. Puedes hacerlo desde tu servidor o desde el navegador del usuario (admite cualquier origen).
  3. Envía el mensaje con attachment_ids: [id, …]: en una conversación con POST /conversations/{id}/messages, o en una nueva con POST /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 con 403. 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. PUT crea 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 Origin se rechaza.
  • Ve también los borradores. Los GET de esta sección devuelven todo, con todos los idiomas y el estado de cada uno, y editable dice 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": "![ajustes](https://helpeen-public.fsn1.your-objectstorage.com/…/ajustes.png)",
    "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 (![demo](….mp4)) 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, con slug, kind, position, editable y translations ({ "es": { "name", "description" } }).

  • PUT /editor/categories/{faq|article}/{slug}: la crea o cambia sus nombres y su orden mientras no contenga nada publicado. El slug va 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, con status, editable, translations y sus videos (cada uno con id, url, provider, position y translations). 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 }. El slug va 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 en position). Otro idioma puede tener su propia versión del vídeo con url en 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}: cambia url, translations o position de 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) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[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>