@extends('layouts.admin') @section('title', 'Manual del Administrador — Olo Chat') @section('content')

📖 Manual del Administrador — Olo Chat

Guía completa para configurar canales sociales, webhooks, autoposting y cron jobs.

{{-- Table of Contents --}}

Índice

1. Arquitectura del Sistema 2. Configurar Telegram 3. Configurar WhatsApp 4. Configurar Facebook 5. Configurar Instagram 6. URLs de Webhooks 7. Autoposting 8. Configurar Cron 9. Flujos Conversacionales 10. Variables de Entorno 11. Troubleshooting 12. Onboarding de Clientes
{{-- 1. Architecture --}}

🏗️ 1. Arquitectura del Sistema

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Telegram   │   │  WhatsApp   │   │  Facebook   │   │  Instagram  │
│  Bot API    │   │  Cloud API  │   │  Messenger  │   │  DM API     │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │                 │
       └────────┬────────┴────────┬────────┘                 │
                │                 │                          │
         ┌──────▼──────┐  ┌──────▼──────┐           ┌──────▼──────┐
         │  Webhook     │  │  Webhook     │           │  Webhook     │
         │  /telegram/  │  │  /whatsapp   │           │  /instagram  │
         └──────┬──────┘  └──────┬──────┘           └──────┬──────┘
                │                 │                          │
                └────────┬────────┴──────────────────────────┘
                         │
                  ┌──────▼──────┐
                  │   Channel    │  ← Resuelve tenant por canal
                  │   Router     │
                  └──────┬──────┘
                         │
                  ┌──────▼──────┐
                  │  ChatBot     │  ← Flujos + KB + AI
                  │  Service     │
                  └──────┬──────┘
                         │
                  ┌──────▼──────┐
                  │   Channel    │  ← Responde por el mismo canal
                  │   Reply Svc  │
                  └─────────────┘

Flujo: Usuario envía mensaje → Webhook recibe → Se resuelve el canal y tenant desde la BD → ChatbotService procesa (flujos + KB + AI) → ChannelReplyService responde por el mismo canal.

{{-- 2. Telegram --}}

2. Configurar Telegram

✅ Más fácil de configurar. No requiere verificación, API 100% gratis, sin límites de mensajes.

Paso a paso:

  1. Abre Telegram y busca @BotFather
  2. Envía /newbot
  3. Define un nombre (ej: "Olorun Asistente") y un username (ej: olorun_asistente_bot)
  4. BotFather te dará un token (ej: 7123456789:AAHbE...)
  5. En el admin: Tenant → Canales → Agregar Telegram → Pegar token → Conectar
  6. El sistema registra el webhook automáticamente vía Telegram API

Webhook URL:

{{ url('/api/webhook/telegram/{BOT_TOKEN}') }}

Personalizar el bot:

  • Envía /setdescription a @BotFather para cambiar la descripción
  • Envía /setuserpic para poner el logo del cliente
  • Envía /setcommands para definir comandos (ej: /start, /menu)
{{-- 3. WhatsApp --}}

3. Configurar WhatsApp

⚠️ Requiere cuenta de Meta Business. Primeros 1,000 conversaciones/mes gratis, luego ~$0.005/msg.

Requisitos previos:

  1. Cuenta en Meta Business Suite
  2. Verificación del negocio (puede tomar 2-7 días)
  3. Número de teléfono dedicado (no puede estar registrado en WhatsApp normal)

Paso a paso:

  1. Ve a developers.facebook.com → Crear App → Tipo: Business
  2. En la app → Productos → WhatsApp → Configurar
  3. Obtén el Phone Number ID y un Access Token permanente
  4. En la sección Webhooks: URL = {{ url('/api/webhook/whatsapp') }}
  5. Verify Token = olorun-wa-verify-2026
  6. Suscríbete al campo messages
  7. En admin: Tenant → Canales → WhatsApp → Pegar Phone Number ID + Token → Conectar

Webhook URL:

{{ url('/api/webhook/whatsapp') }}

Variable de entorno necesaria:

WHATSAPP_VERIFY_TOKEN=olorun-wa-verify-2026
{{-- 4. Facebook --}}

4. Configurar Facebook Messenger

⚠️ Requiere Facebook App Review (2-5 días hábiles) para acceder a Messenger API en producción.

Paso a paso:

  1. En developers.facebook.com → Tu App → Productos → Messenger → Configurar
  2. Conecta tu Página de Facebook
  3. Genera un Page Token (token de larga duración)
  4. En Webhooks: URL = {{ url('/api/webhook/facebook') }}
  5. Verify Token = olorun-fb-verify-2026
  6. Suscribirte a: messages, messaging_postbacks
  7. Solicitar permisos: pages_messaging
  8. En admin: Tenant → Canales → Facebook → Page ID + Token → Conectar

Webhook URL:

{{ url('/api/webhook/facebook') }}
FACEBOOK_VERIFY_TOKEN=olorun-fb-verify-2026
{{-- 5. Instagram --}}

5. Configurar Instagram

ℹ️ Instagram usa la misma Facebook App. Si ya tienes Facebook configurado, solo necesitas activar Instagram Messaging.

Requisitos:

  • Cuenta de Instagram Business o Creator
  • Conectada a una Página de Facebook
  • Permiso instagram_manage_messages en la app

Webhook URL:

{{ url('/api/webhook/instagram') }}
INSTAGRAM_VERIFY_TOKEN=olorun-ig-verify-2026
{{-- 6. Webhooks Summary --}}

🔗 6. Resumen de Webhook URLs

Plataforma Método URL
Telegram POST {{ url('/api/webhook/telegram/{BOT_TOKEN}') }}
WhatsApp GET/POST {{ url('/api/webhook/whatsapp') }}
Facebook GET/POST {{ url('/api/webhook/facebook') }}
Instagram GET/POST {{ url('/api/webhook/instagram') }}
⚠️ Importante: Estas URLs deben ser accesibles públicamente vía HTTPS. El servidor debe tener SSL válido.
{{-- 7. Autoposting --}}

📣 7. Autoposting

El sistema permite publicar posts en Facebook e Instagram desde el panel de admin.

3 modos de publicación:

📝 Borrador

Guarda sin publicar. Puedes editarlo después.

⏰ Programar

Se publica automáticamente a la fecha/hora seleccionada vía cron.

🚀 Publicar Ahora

Se envía inmediatamente a las plataformas seleccionadas.

Plataformas soportadas para posting:

  • Facebook — Post de texto o con imagen en el muro de la página
  • Instagram — Requiere imagen obligatoriamente (API de Instagram no permite solo texto)
🚫 Telegram y WhatsApp NO soportan autoposting — estas plataformas son solo para mensajería 1-a-1 con el chatbot.
{{-- 8. Cron --}}

⏱️ 8. Configurar Cron Job

Para que los posts programados se publiquen automáticamente, necesitas un cron job.

Agregar al crontab del servidor:

* * * * * cd /home/olorvslb/olo.run/escan && php artisan posts:publish >> /dev/null 2>&1

En cPanel:

  1. Ve a cPanel → Cron Jobs
  2. Frecuencia: Every Minute (* * * * *)
  3. Comando: cd /home/olorvslb/olo.run/escan && php artisan posts:publish >> /dev/null 2>&1

Probar manualmente:

php artisan posts:publish
{{-- 9. Flows --}}

🔀 9. Flujos Conversacionales

Cada tenant tiene un árbol de flujos que define las opciones del chatbot.

Estructura:

🤖 Bot dice: "Hola, ¿en qué puedo ayudarte?"

1️⃣ Información        → Respuesta de texto
2️⃣ Productos           → Sub-menú
   └─ 1. Servicio A    → Respuesta
   └─ 2. Servicio B    → Respuesta
   └─ 3. Servicio C    → Respuesta
3️⃣ Precios             → Respuesta
4️⃣ FAQ                 → Sub-menú (agregar preguntas)
5️⃣ Demo                → Acción: WhatsApp asesor
6️⃣ Soporte             → Acción: crear ticket
7️⃣ Persona             → Acción: WhatsApp asesor
8️⃣ Contacto            → Acción: mostrar datos

0️⃣ → Siempre vuelve al menú principal

Tipos de acción:

👤 advisor — Redirige a WhatsApp del asesor
📞 contact — Muestra datos de contacto
🎯 demo_link — Envía link de demo
🎫 ticket — Crea ticket de soporte

Al crear un tenant, se generan 11 nodos automáticamente. El admin puede editarlos, agregar sub-nodos, o crear flujos completamente nuevos.

{{-- 10. Env --}}

🔐 10. Variables de Entorno

# Verify tokens para webhooks (puedes cambiarlos)

WHATSAPP_VERIFY_TOKEN=olorun-wa-verify-2026

FACEBOOK_VERIFY_TOKEN=olorun-fb-verify-2026

INSTAGRAM_VERIFY_TOKEN=olorun-ig-verify-2026

# OpenAI (para respuestas AI del chatbot)

OPENAI_API_KEY=sk-...

CHATBOT_AI_MODEL=gpt-4o-mini

CHATBOT_MAX_TOKENS=800

CHATBOT_TEMPERATURE=0.7

{{-- 11. Troubleshooting --}}

🔧 11. Troubleshooting

El bot de Telegram no responde

  • Verifica que el token esté correcto en Canales
  • Revisa los logs: storage/logs/laravel.log
  • Verifica que el webhook se registró: https://api.telegram.org/bot{TOKEN}/getWebhookInfo
  • El servidor debe tener SSL (HTTPS) válido

WhatsApp no recibe mensajes

  • Verifica el Verify Token en Meta Developer Console
  • Asegura que el campo messages esté suscrito
  • Verifica que el Phone Number ID y Access Token sean correctos
  • El Access Token puede expirar — usa uno de larga duración

Posts no se publican automáticamente

  • Verifica que el cron esté configurado: crontab -l
  • Ejecuta manual: php artisan posts:publish
  • Revisa el status del post en el listado (puede estar en "Error")
  • Usa "Reintentar" para re-publicar posts fallidos

Error 403 en webhook de Facebook/Instagram

  • El Verify Token en el .env debe coincidir con el de Meta Developer
  • La URL debe ser HTTPS con certificado válido
  • Verifica que la ruta no esté bloqueada por el middleware CSRF
{{-- 12. Client Onboarding --}}

👥 12. Onboarding de Clientes

Cuando agregas un nuevo cliente:

  1. Crear Tenant — Logo, nombre, color, plan. Se crean flujos + canal web automáticamente.
  2. Personalizar Flujos — Editar los 11 nodos creados con el contenido real del cliente.
  3. Conectar Canales — Pedir al cliente los tokens de sus redes (o crearlos tú).
  4. Agregar KB — Cargar artículos de Knowledge Base relevantes al negocio.
  5. Instalar Widget — Darle el código embed para su sitio web.
  6. Probar — Enviar mensajes de prueba por cada canal conectado.

Checklist por cliente:

☐ Tenant creado con logo y configuración

☐ Flujos personalizados con info real

☐ Al menos 1 canal social conectado

☐ Widget instalado en su sitio web

☐ Prueba exitosa de mensajería

☐ Knowledge Base con al menos 5 artículos

Última actualización: {{ now()->format('d/m/Y H:i') }} · Olo Chat v3.0 · Solo visible para administradores
@endsection