Helpium

Guía de Integración de la API del Cliente

La API del Cliente de Helpium te permite interactuar programáticamente con el widget de chat, identificar clientes y gestionar conversaciones desde tu aplicación.

Autenticación

Todas las solicitudes de la API del Cliente requieren la clave API de tu espacio de trabajo enviada como un encabezado:

X-API-Key: your_widget_key_here

Puedes encontrar tu clave API en Configuración → Canales → Widget.

URL Base

Todos los puntos finales están precedidos por /api/customer. Por ejemplo:

GET https://your-workspace.helpium.io/api/customer/widget/settings

Puntos Finales Disponibles

Configuración del Widget

GET /api/customer/widget/settings

Devuelve la configuración de tu widget, incluyendo colores, posición, mensaje de saludo y estado de horas laborales.

Buscar Artículos

POST /api/customer/search
Body: { "query": "cómo restablezco mi contraseña" }

Busca en tu base de conocimientos utilizando búsqueda semántica impulsada por IA. Devuelve los artículos más relevantes.

Respuesta de IA

POST /api/customer/search/answer
Body: { "query": "cómo restablezco mi contraseña" }

Devuelve una respuesta generada por IA basada en los artículos de tu base de conocimientos.

Crear Conversación

POST /api/customer/conversations
Body: { "message": "Necesito ayuda con la facturación" }

Crea una nueva conversación y devuelve un token de widget para mensajes posteriores.

Enviar Mensaje

POST /api/customer/conversations/{token}/messages
Body: { "body": "¿Puedes revisar mi factura?" }

Envía un mensaje en una conversación existente.

Identificar Cliente

POST /api/customer/tracking/identify
Body: {
    "email": "customer@example.com",
    "name": "Jane Smith",
    "widget_token": "existing_conversation_token"
}

Vincula la identidad de un cliente a sus conversaciones. Esto permite soporte personalizado e historial de conversaciones a través de sesiones.

Identificación de Clientes con Tokens Bearer

Para usuarios autenticados en tu aplicación, puedes pasar un token bearer de Sanctum durante la identificación:

Helpium.identify({
    email: user.email,
    name: user.name,
    bearerToken: sanctumToken,
});

Esto habilita Acciones de IA que necesitan acceder a la API de tu aplicación en nombre del cliente. El token se almacena de forma segura y se envía como un encabezado Authorization: Bearer cuando la IA llama a tus puntos finales.

Límites de Tasa

Las solicitudes de la API están limitadas por tasa por espacio de trabajo. Consulta el artículo Límites y Uso de la API para más detalles.

Manejo de Errores

Todos los errores de la API devuelven un formato JSON consistente:

{
    "error": {
        "message": "Descripción del error",
        "status": 422,
        "code": "invalid_input"
    }
}

Códigos de error comunes: unauthenticated (401), not_found (404), invalid_input (422), too_many_requests (429).

Guía de Integración de API de Cliente