Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KevinhosUTP/Automatizacion-Lurwis/llms.txt

Use this file to discover all available pages before exploring further.

El sistema de Automatización Lurwis interactúa con múltiples APIs para recibir mensajes, enviar respuestas y gestionar buffers temporales.

​
Webhook Principal - Meta (Facebook)

​
POST /meta-verify

Webhook configurado en n8n que recibe eventos de WhatsApp Business API desde Meta (Facebook).
​
required
Modo de verificación enviado por Meta.Valor esperado: subscribe
​
required
Token de verificación configurado en Meta Developer Console.Valor: meta-verify
​
Challenge enviado por Meta durante la configuración inicial del webhook.

​
Verificación inicial (GET)

Meta envía una petición GET para validar el webhook: 
GET /meta-verify?hub.mode=subscribe&hub.verify_token=meta-verify&hub.challenge=1234567890
​
response
string
El servidor debe responder con el valor exacto de hub.challenge.
​
status
number
Código HTTP 200 para verificación exitosa.

​
Recepción de mensajes (POST)

Cuando un cliente envía un mensaje por WhatsApp, Meta lo reenvía a este webhook: 
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "746650594705809",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15551933641",
              "phone_number_id": "947279508470714"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kevo"
                },
                "wa_id": "51900769907"
              }
            ],
            "messages": [
              {
                "from": "51900769907",
                "id": "wamid.HBgLNTE5MDA3Njk5MDcVAgASGBYzRUIwNDRDRDQ4MzBCQ0U5MjE0QTI2AA==",
                "timestamp": "1771142227",
                "text": {
                  "body": "Quiero hacer un pedido"
                },
                "type": "text"
              }
            ],
            "statuses": []
          },
          "field": "messages"
        }
      ]
    }
  ]
}
​
entry[].changes[].value.messages[]
array
Array de mensajes recibidos. Puede estar vacío (mensaje de estado).
​
entry[].changes[].value.messages[].from
string
Número de teléfono del remitente en formato internacional.
​
entry[].changes[].value.messages[].text.body
string
Contenido del mensaje de texto enviado por el cliente.
​
entry[].changes[].value.metadata.phone_number_id
string
ID del número de WhatsApp Business usado para responder.
​
entry[].changes[].value.statuses[]
array
Array de actualizaciones de estado (entregado, leído). Cuando está presente, messages suele estar vacío.

​
Validación y Filtrado

El webhook implementa múltiples capas de validación: 
if (hub.mode === 'subscribe' && hub.verify_token === 'meta-verify') {
  return hub.challenge; // Status 200
} else {
  return 'Forbidden'; // Status 403
}
Filtra ejecuciones donde:
  • messages está vacío
  • text.body está vacío
  • Solo hay statuses (sin mensaje nuevo)
Esto evita procesar webhooks de confirmación de lectura o entrega.
Limpia y estructura los datos relevantes:
{
  from: "51900769907",
  "text.body": "Quiero hacer un pedido",
  "id cliente": "wamid.HBg...",
  "id mensajero": "947279508470714",
  profile_name: "Kevo",
  mensaje_real: true
}

​
WhatsApp Business API (Meta)

​
POST https://graph.facebook.com/v21.0/{phone_number_id}/messages

Endpoint oficial de Meta para enviar mensajes de WhatsApp.
​
phone_number_id
string
required
ID del número de WhatsApp Business (obtenido desde el webhook entrante).Ejemplo: 947279508470714

​
Headers

Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

​
Request Body

{
  "messaging_product": "whatsapp",
  "to": "51900769907",
  "type": "text",
  "text": {
    "body": "¡Hola! Bienvenido a Picantería Lurwis 🦐. ¿En qué puedo ayudarte?"
  }
}
​
messaging_product
string
required
Siempre whatsapp
​
to
string
required
Número de teléfono del destinatario en formato internacional (sin signos +).
​
type
string
required
Tipo de mensaje.Valores soportados: text, image, document, template
​
text.body
string
required
Contenido del mensaje de texto. Soporta formato básico de WhatsApp:
  • *negrita*
  • _cursiva_
  • Emojis

​
Response

​
messages[].id
string
ID único del mensaje enviado (WAMID).
​
messages[].message_status
string
Estado inicial del mensaje.Valores: accepted, queued
{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "51900769907",
      "wa_id": "51900769907"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLNTE5MDA3Njk5MDcVAgARGBI4OTNENDI2MTFCNDBBQTE2AA==",
      "message_status": "accepted"
    }
  ]
}
Si el token de acceso es inválido o el número no está registrado en WhatsApp Business, recibirás un error 401 o 403.

​
Redis API (Upstash)

El sistema utiliza Redis para gestionar el buffer temporal de mensajes.

​
SET - Guardar buffer

SET buffer_51900769907 "Hola\nQuiero hacer un pedido\n2 ceviches" EX 30
​
key
string
required
Formato: buffer_{telefono}
​
value
string
required
Mensajes concatenados separados por saltos de línea (\n).
​
EX
number
TTL (Time To Live) en segundos. Por defecto: 30 segundos.

​
SET - Guardar timestamp

SET ts_51900769907 "1771142230000" EX 30
​
key
string
required
Formato: ts_{telefono}
​
value
string
required
Timestamp Unix en milisegundos del último mensaje.

​
SET - Guardar metadata

SET meta_51900769907 "947279508470714" EX 120
​
key
string
required
Formato: meta_{telefono}
​
value
string
required
ID del número de WhatsApp Business para responder.
​
EX
number
TTL: 120 segundos (mayor que buffer y timestamp).

​
GET - Leer buffer

GET buffer_51900769907
Retorna el contenido del buffer o null si no existe o expiró.

​
KEYS - Buscar usuarios activos

KEYS ts_*
Retorna un array de todas las keys de timestamp activas (usuarios con mensajes pendientes). 
{
  "ts_51900769907": "1771142230000",
  "ts_51987654321": "1771142240000"
}

​
DEL - Eliminar buffer procesado

DEL buffer_51900769907
DEL ts_51900769907
DEL meta_51900769907
Elimina todas las keys asociadas a un usuario después de procesar sus mensajes.

​
Google Gemini API

El sistema utiliza modelos de Google Gemini a través de LangChain para los agentes IA.

​
Modelos utilizados

​
model
string
Modelo de IA utilizado.
  • Gemini Flash: Para clasificación rápida y detección de intenciones
  • Gemini Pro: Para el agente de pedidos (razonamiento complejo)
Las credenciales de API se gestionan de forma segura en n8n con el nombre “Modelo Lurwis”.

​
Resumen de Flujo de APIs

​
Manejo de Errores

Se envía cuando:
  • Token de verificación incorrecto
  • hub.mode no es “subscribe”
Solución: Verificar configuración en Meta Developer Console.
Token de acceso inválido o expirado.Solución: Regenerar token en Meta Business Manager.
Buffer expiró antes de ser procesado (TTL venció).Solución: Ajustar TTL o reducir intervalo del cron procesador.
Conexión a base de datos falló.Solución: Verificar Session Pooler y credenciales en n8n.