Referencia de la API

API REST para el panel de control, widget y webhooks de HelpStack.

Datos rápidos#

Espere un 404 en /api y un 401 en los endpoints autenticados. No existe ninguna ruta en https://helpstack.eu/api — devuelve 404 por diseño, porque la API es un conjunto de sub-rutas (/api/conversations, /api/channels, …), no una raíz navegable. Abrir un endpoint real como /api/conversations en un navegador devuelve 401 (sin cookie de sesión), lo que confirma que existe y está protegido por autenticación. Ninguna de las dos respuestas es un error.

Modelo de autenticación — léa esto primero#

Actualmente no existe un sistema público de clave de API o token bearer para llamantes externos. No busque una "clave de API" — no existe. La API del panel/interna se autentica con la cookie de sesión NextAuth de un usuario autenticado, y cada solicitud queda automáticamente limitada a la organización de ese usuario mediante middleware (withOrganization / withAdmin / withAgent). Estos endpoints son consumidos por la interfaz del panel de HelpStack.

Para llamar a endpoints del panel desde fuera del navegador debe reproducir una cookie de sesión autenticada. Si necesita acceso de máquina a máquina, las superficies públicas admitidas son:

• Endpoints del widget — públicos, con límite de tasa por IP/visitante (consulte Inserción del widget).
• Endpoints de webhooks — públicos, verificados por token + firma HMAC (consulte Webhooks).

Trate cualquier cosa que requiera una cookie de sesión como "verifique contra su despliegue" para uso programático.

Envoltorio de respuesta#

Todas las rutas de la API devuelven un envoltorio estándar.

Éxito

{ "success": true, "data": { } }

Error

{
  "success": false,
  "error": {
    "message": "Human-readable message",
    "code": "OPTIONAL_CODE",
    "fields": { "fieldName": ["error 1"] }
  }
}

code y fields son opcionales. fields se rellena para errores de validación (Zod) con mensajes por campo.

Códigos de error y estado HTTP#

Los errores son producidos por clases de error tipadas y un manejador central. Mapa de alto nivel:

Los fallos de validación Zod devuelven 400 con code: "VALIDATION_ERROR" y un objeto fields. Los errores inesperados devuelven 500 con un mensaje genérico ("An unexpected error occurred"); el detalle real solo se registra en el servidor.

Qué puedes llamar realmente desde fuera del navegador#

Dos superficies, y solo dos:

Si estás construyendo una integración, esas dos páginas son lo que buscas. Todo lo del catálogo de abajo necesita una sesión de navegador.

Catálogo de endpoints (autenticados por sesión, no son una superficie de integración)#

Estos endpoints los consume el panel de HelpStack. Se autentican con una cookie de sesión de NextAuth, así que llamarlos programáticamente significa reproducir una sesión de navegador iniciada. Están documentados como referencia y para quienes trabajan en HelpStack, no como una vía de integración compatible, y sus formas pueden cambiar cuando cambie el panel.

Una API con alcance y autenticada por token está diseñada pero no construida. Hasta que exista, trata este catálogo como interno.

Roles: un endpoint marcado como ADMIN requiere administrador (withAdmin), AGENT requiere agente o superior (withAgent), Session requiere cualquier miembro autenticado de la organización (withOrganization).

Canales

Crear canal — POST /api/channels (cuerpo verificado, createChannelSchema):

{
  "type": "WEBSITE_CHAT",
  "name": "Website Chat",
  "region": "eu",
  "defaultLanguage": "en",
  "autoTranslate": true,
  "translateToLanguage": "en",
  "fallbackLanguage": "sl",
  "aiProviderId": "PROVIDER_ID",
  "credentials": {},
  "responseTemplate": {},
  "autoReply": false,
  "autoApprove": false,
  "autoEnhance": false
}

Las formas de credencial por tipo de canal (credentials) se validan por separado — p. ej. Email requiere { host, port, username, password, from, secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned? }; Facebook requiere { pageId, accessToken, appSecret? }; Instagram requiere { accountId, accessToken }. Las credenciales se almacenan cifradas (AES-256-GCM).

Conversaciones

Valores del filtro status: OPEN | PENDING | CLOSED | ARCHIVED. pageSize está limitado a 100 (por defecto 20).

Enviar mensaje — POST /api/conversations/[id]/messages (cuerpo verificado, sendMessageSchema):

{
  "conversationId": "CONVERSATION_ID",
  "content": "Thanks for reaching out — here's how to fix that.",
  "attachments": ["storage/path/file.png"]
}

Comportamiento: el mensaje se crea como OUTBOUND. Si el canal tiene autoTranslate activado y se conoce el idioma del cliente, el mensaje se crea sin aprobar y se traduce en segundo plano (el agente aprueba antes de enviarlo). Enviar consume tokens del plan; si la organización se queda sin tokens, la ruta devuelve 402 con code: "INSUFFICIENT_TOKENS". En caso de éxito devuelve el mensaje creado con HTTP 201.

Mensajes

FAQs

Medios

Notificaciones

Proveedores de IA

Herramientas de agente

Consulte Herramientas de agente personalizadas para la anatomía completa de la herramienta.

Widget (público)

Consulte Inserción del widget para los payloads.

Webhooks (público)

Consulte Webhooks para los detalles del handshake y la firma.

Relacionado#

• Inserción del widget
• Webhooks
• Canal de email
• Herramientas de agente personalizadas
• Guía de canales
• Glosario