El widget de Lia cubre la mayoría de casos de uso. Pero si necesitas integraciones personalizadas, construir tu propia interfaz, o conectar Lia con tus sistemas internos, la API es tu herramienta.

Este tutorial está dirigido a desarrolladores o equipos técnicos que quieren ir más allá del widget estándar.

¿Cuándo usar la API?

La API de Lia es útil para:

Interfaz personalizada: Crear tu propia UI de chat en lugar del widget
Integraciones con CRM: Sincronizar conversaciones con Salesforce, HubSpot, etc.
Apps móviles: Integrar el chat en tu app iOS/Android
Automatizaciones: Conectar con Zapier, Make, n8n
Análisis avanzado: Extraer datos de conversaciones para BI
Chatbots en otros canales: Telegram, Slack, Discord

Autenticación

Obtener tu API Key

Ve a app.hellolia.es
Configuración > API
Haz clic en "Generar API Key"
Copia la key (solo se muestra una vez)

Importante:

Guarda la key de forma segura
No la expongas en código frontend
Puedes regenerarla si la pierdes (invalida la anterior)

Uso de la API Key

Incluye la key en el header de todas las peticiones:

Authorization: Bearer tu_api_key_aqui

O como parámetro (menos recomendado):

?api_key=tu_api_key_aqui

Endpoints principales

Base URL

https://api.hellolia.es/v1

1. Enviar mensaje y obtener respuesta

POST /chat
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "session_id": "session_123",
  "message": "¿Cuánto tardáis en enviar?"
}

Respuesta:

{
  "success": true,
  "response": {
    "message": "Los pedidos se envían en 24-48 horas laborables. El tiempo de entrega depende de tu ubicación: península 2-3 días, islas 5-7 días. ¿Desde dónde nos escribes?",
    "sentiment": "neutral",
    "confidence": 0.95,
    "should_escalate": false
  },
  "session": {
    "id": "session_123",
    "messages_count": 2,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

2. Crear nueva sesión

POST /sessions
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "user_email": "cliente@email.com",
  "user_name": "María García",
  "metadata": {
    "source": "app_movil",
    "user_id": "12345"
  }
}

Respuesta:

{
  "success": true,
  "session": {
    "id": "session_abc123",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

3. Obtener historial de sesión

GET /sessions/{session_id}
Authorization: Bearer tu_api_key

Respuesta:

{
  "success": true,
  "session": {
    "id": "session_123",
    "user_email": "cliente@email.com",
    "user_name": "María García",
    "messages": [
      {
        "role": "user",
        "content": "Hola, tengo una duda",
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "role": "assistant",
        "content": "¡Hola María! Claro, ¿en qué puedo ayudarte?",
        "timestamp": "2024-01-15T10:30:01Z"
      }
    ],
    "sentiment_history": ["neutral", "positive"],
    "escalated": false,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

4. Listar sesiones

GET /sessions?limit=50&offset=0&status=active
Authorization: Bearer tu_api_key

Parámetros opcionales:

limit: Número de resultados (max 100)
offset: Paginación
status: active, escalated, closed
from_date: Fecha inicio (ISO 8601)
to_date: Fecha fin

5. Escalar sesión a humano

POST /sessions/{session_id}/escalate
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "reason": "Cliente solicita hablar con humano",
  "priority": "high",
  "notify_channels": ["whatsapp", "email"]
}

6. Cerrar sesión

POST /sessions/{session_id}/close
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "resolution": "resolved",
  "notes": "Cliente satisfecho con la respuesta sobre envíos"
}

7. Actualizar base de conocimiento

POST /knowledge-base
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "items": [
    {
      "title": "Política de envíos actualizada",
      "content": "A partir del 1 de febrero, los envíos a península son gratis a partir de 40€.",
      "category": "envios",
      "tags": ["envio", "gratis", "peninsula"]
    }
  ]
}

8. Obtener analíticas

GET /analytics?from=2024-01-01&to=2024-01-31
Authorization: Bearer tu_api_key

Respuesta:

{
  "success": true,
  "analytics": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "conversations": {
      "total": 1250,
      "resolved_by_ai": 980,
      "escalated": 270
    },
    "messages": {
      "total": 5430,
      "avg_per_conversation": 4.3
    },
    "sentiment": {
      "positive": 45,
      "neutral": 40,
      "negative": 15
    },
    "top_topics": [
      {"topic": "envios", "count": 320},
      {"topic": "devoluciones", "count": 210},
      {"topic": "tallas", "count": 180}
    ],
    "avg_response_time_ms": 850
  }
}

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos.

Configurar webhook

POST /webhooks
Content-Type: application/json
Authorization: Bearer tu_api_key

{
  "url": "https://tu-servidor.com/webhook/lia",
  "events": ["session.created", "session.escalated", "message.received"],
  "secret": "tu_secreto_para_verificar"
}

Eventos disponibles

session.created: Nueva conversación iniciada
session.escalated: Conversación escalada a humano
session.closed: Conversación cerrada
message.received: Nuevo mensaje del usuario
message.sent: Respuesta enviada por Lia
sentiment.negative: Sentimiento negativo detectado

Payload del webhook

{
  "event": "session.escalated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "session_id": "session_123",
    "user_email": "cliente@email.com",
    "reason": "frustration_detected",
    "last_message": "Esto es ridículo, llevo media hora esperando"
  },
  "signature": "sha256_hmac_del_payload"
}

Verificar firma

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Ejemplos de integración

Ejemplo 1: Chat en React

import { useState, useEffect } from 'react';

function ChatWidget() {
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState('');
  const [sessionId, setSessionId] = useState(null);

  useEffect(() => {
    // Crear sesión al montar
    createSession();
  }, []);

  async function createSession() {
    const response = await fetch('https://api.hellolia.es/v1/sessions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer TU_API_KEY'
      },
      body: JSON.stringify({
        metadata: { source: 'react_app' }
      })
    });
    const data = await response.json();
    setSessionId(data.session.id);
  }

  async function sendMessage() {
    if (!input.trim() || !sessionId) return;

    // Añadir mensaje del usuario
    setMessages(prev => [...prev, { role: 'user', content: input }]);

    const userMessage = input;
    setInput('');

    // Enviar a la API
    const response = await fetch('https://api.hellolia.es/v1/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer TU_API_KEY'
      },
      body: JSON.stringify({
        session_id: sessionId,
        message: userMessage
      })
    });

    const data = await response.json();

    // Añadir respuesta
    setMessages(prev => [...prev, {
      role: 'assistant',
      content: data.response.message
    }]);
  }

  return (
    <div className="chat-widget">
      <div className="messages">
        {messages.map((msg, i) => (
          <div key={i} className={`message ${msg.role}`}>
            {msg.content}
          </div>
        ))}
      </div>
      <input
        value={input}
        onChange={e => setInput(e.target.value)}
        onKeyPress={e => e.key === 'Enter' && sendMessage()}
        placeholder="Escribe tu mensaje..."
      />
      <button onClick={sendMessage}>Enviar</button>
    </div>
  );
}

Ejemplo 2: Integración con Zapier/Make

Usa webhooks para conectar con otras herramientas:

Configura un webhook en Lia para session.escalated
En Zapier/Make, crea un "Webhook trigger"
Cuando se escale una conversación:
- Crea un ticket en Zendesk
- Envía un mensaje a Slack
- Añade una fila a Google Sheets
- Actualiza el CRM

Ejemplo 3: Sincronizar con CRM

import requests

def sync_conversation_to_crm(session_id):
    # Obtener conversación de Lia
    response = requests.get(
        f'https://api.hellolia.es/v1/sessions/{session_id}',
        headers={'Authorization': 'Bearer TU_API_KEY'}
    )
    session = response.json()['session']

    # Formatear para CRM
    crm_data = {
        'contact_email': session['user_email'],
        'conversation_summary': '\n'.join([
            f"{m['role']}: {m['content']}"
            for m in session['messages']
        ]),
        'sentiment': session['sentiment_history'][-1],
        'source': 'lia_chatbot'
    }

    # Enviar a CRM (ejemplo HubSpot)
    requests.post(
        'https://api.hubspot.com/crm/v3/objects/notes',
        headers={'Authorization': 'Bearer HUBSPOT_KEY'},
        json=crm_data
    )

Límites y buenas prácticas

Rate limits

Estándar: 100 requests/minuto
Pro: 500 requests/minuto
Enterprise: Personalizado

Si excedes el límite, recibirás error 429.

Buenas prácticas

Cachea sesiones: No crees una sesión nueva para cada mensaje
Maneja errores: Implementa reintentos con backoff exponencial
Usa webhooks: Mejor que polling para eventos en tiempo real
No expongas la API key: Usa un backend para llamadas a la API
Monitoriza uso: Revisa las analíticas regularmente

Soporte para desarrolladores

Documentación completa: docs.hellolia.es
Postman collection: Disponible en la documentación
Sandbox: Entorno de pruebas disponible
Soporte técnico: devs@hellolia.es

¿Necesitas ayuda con tu integración? Nuestro equipo técnico puede asistirte. Contacta en hellolia.es o escribe a devs@hellolia.es.

Cómo usar la API de Lia para integraciones avanzadas

¿Cuándo usar la API?

Autenticación

Obtener tu API Key

Uso de la API Key

Endpoints principales

Base URL

1. Enviar mensaje y obtener respuesta

2. Crear nueva sesión

3. Obtener historial de sesión

4. Listar sesiones

5. Escalar sesión a humano

6. Cerrar sesión

7. Actualizar base de conocimiento

8. Obtener analíticas

Webhooks

Configurar webhook

Eventos disponibles

Payload del webhook

Verificar firma

Ejemplos de integración

Ejemplo 1: Chat en React

Ejemplo 2: Integración con Zapier/Make

Ejemplo 3: Sincronizar con CRM

Límites y buenas prácticas

Rate limits

Buenas prácticas

Soporte para desarrolladores