# 📘 Manual Técnico Oficial: Conexión, Integración y Alta de Agentes Zilliad AI **Versión del Sistema:** 2026.5 (Producción Omnicanal Multi-Rubro) **Plataforma Central:** https://ai.zilliad.com **Arquitectura:** Supabase PostgreSQL Multi-Tenant + n8n Omnichannel Orchestrator + Google Gemini 2.5 Flash / Claude / OpenAI --- ## 📚 Biblioteca de Manuales Complementarios * 🚀 **[Manual Maestro de Configuración Inicial 100% Operativo](file:///C:/Users/totoc/Downloads/Nueva%20carpeta/zilliad-platform/docs/MANUAL_CONFIGURACION_INICIAL_100_OPERATIVO.md):** Guía completa de 7 fases desde el alta hasta la verificación final. * 🏢 **[Manual Operativo por Rubros y Nichos](file:///C:/Users/totoc/Downloads/Nueva%20carpeta/zilliad-platform/docs/MANUAL_OPERATIVO_POR_RUBROS.md):** Directivas, tríadas de agentes y guardrails para los 8 rubros principales (Gastronomía, Salud, Inmobiliarias, Legal, Hoteles, Concesionarias, E-Commerce, Gimnasios). * 📱 **[Manual del Cliente For Dummies](file:///C:/Users/totoc/Downloads/Nueva%20carpeta/zilliad-platform/docs/MANUAL_CLIENTE_FOR_DUMMIES.md):** Instructivo no técnico para entregarle al dueño del negocio para instalar la PWA y gestionar sus ventas. --- ## 📑 Tabla de Contenidos 1. Arquitectura General y Flujo de Alta (Onboarding) 2. Conexión con WhatsApp (Cloud API Oficial & QR Baileys) 3. Conexión con Redes Sociales (Instagram DM & Messenger) 4. Conexión con Telegram 5. Integración en el Sitio Web del Cliente (Widget Flotante & Embebido) 6. Sincronización con CRMs y Bases de Datos (HubSpot, Salesforce, Sheets) 7. Protocolo de Seguridad, Semáforos en Vivo y Handoff Humano --- ## 1. Arquitectura General y Flujo de Alta (Onboarding) ### 1.1. Checklist Técnico para Dar de Alta a un Nuevo Cliente Cada cliente nuevo que contrata el servicio (sea **1 Agente por $150 USD/m** o el **Ecosistema Completo de 3 Agentes por $299 USD/m**) atraviesa los siguientes 5 pasos en el panel de administración: #### Paso 1: Generación del Tenant en Supabase Ejecutar la inserción en la tabla `public.clients`: ```sql INSERT INTO public.clients ( business_name, owner_name, email, phone, country, industry, plan_tier, setup_fee_usd, mrr_usd, messages_limit, preferred_language ) VALUES ( 'Restaurante Don Julio', 'Matías Pérez', 'contacto@donjulio.com', '+5491145678900', 'Argentina', 'Gastronomía', 'full_ecosystem', 300.00, 299.00, 5000, 'es' ) RETURNING id; ``` > Esto genera un `client_id` (UUID único) que se utilizará como cabecera o parámetro en todos los webhooks y widgets. #### Paso 2: Carga y Vectorización de la Base de Conocimiento En la pestaña **"🎓 Entrenar y Calibrar Agente (IA)"**: 1. Subir la lista de precios, menú, políticas de reserva, horarios de atención o FAQs en PDF o texto. 2. Definir el tono de voz: - *Gastronomía / Hotelería / Turismo:* Cálido, hospitalario, sugerente. - *Legal / Clínicas / Farmacias:* Empático, riguroso, formal y seguro. - *E-commerce / Consorcios:* Ágil, resolutivo y directo. 3. Se genera el `system_prompt` específico guardado en la tabla `public.agents`. #### Paso 3: Asignación de Bolsa de Tokens y Canales Se le asignan los 5.000 mensajes mensuales base de su cuota. Si adquiere paquetes adicionales (Bolsa Central Stripe), se acreditan inmediatamente a su registro. --- ## 2. Conexión con WhatsApp ### Método A: WhatsApp Cloud API Oficial de Meta (Recomendado para Empresas) 1. **Crear App en Meta for Developers:** - Ingresar a developers.facebook.com con la cuenta Business de la empresa. - Crear una aplicación de tipo Business y añadir el producto WhatsApp. 2. **Obtener Credenciales de Producción:** - `PHONE_NUMBER_ID`: Identificador del número telefónico. - `WABA_ID` (WhatsApp Business Account ID). - `PERMANENT_ACCESS_TOKEN`: Generado desde Meta Business Settings > System Users con permiso `whatsapp_business_messaging`. 3. **Configurar el Webhook en Meta:** - URL de Callback: `https://tu-n8n.com/webhook/zilliad-omnicanal-webhook` - Token de Verificación (`VERIFY_TOKEN`): Definir una cadena secreta (ej. `zilliad_meta_verify_2026`). - Campos de Suscripción: Marcar únicamente `messages`. 4. **Envío de Respuestas Salientes (POST HTTP Request en n8n):** - URL: `https://graph.facebook.com/v21.0/{{ $json.phoneId }}/messages` - Headers: `Authorization: Bearer {{ $env.META_ACCESS_TOKEN }}`, `Content-Type: application/json` - Payload JSON: ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "{{ $json.customerPhone }}", "type": "text", "text": { "preview_url": false, "body": "{{ $json.aiResponseText }}" } } ``` ### Método B: Conexión Rápida vía Código QR (Evolution API / Baileys) *Ideal para clientes que quieren usar su número actual de WhatsApp Business sin trámites de verificación en Meta.* 1. Despliegue del contenedor Evolution API: ```bash docker run -d --name zilliad-evolution -p 8080:8080 -e AUTHENTICATION_API_KEY=tu_clave_maestra_zilliad atendai/evolution-api:v2.1.0 ``` 2. Crear Instancia para el Comercio: ```bash curl -X POST "http://localhost:8080/instance/create" \ -H "apikey: tu_clave_maestra_zilliad" \ -H "Content-Type: application/json" \ -d '{ "instanceName": "cliente_don_julio", "token": "token_seguro_don_julio_123", "qrcode": true, "webhook": "https://tu-n8n.com/webhook/zilliad-omnicanal-webhook", "webhook_by_events": true, "events": ["MESSAGES_UPSERT"] }' ``` 3. El cliente escanea el código QR desde WhatsApp > Dispositivos Vinculados y la sesión queda activa 24/7. --- ## 3. Conexión con Redes Sociales (Instagram DM & Messenger) 1. Requisitos: Fanpage de Facebook vinculada a la cuenta profesional de Instagram. 2. Permisos en Meta: `instagram_manage_messages`, `pages_manage_metadata`, `pages_messaging`. 3. Webhook: Suscribir eventos `messages` en Meta App. 4. Envío de Respuesta: ```http POST https://graph.facebook.com/v21.0/me/messages Authorization: Bearer {{ $env.META_PAGE_ACCESS_TOKEN }} Content-Type: application/json { "recipient": { "id": "{{ $json.senderId }}" }, "message": { "text": "{{ $json.aiResponseText }}" } } ``` --- ## 4. Conexión con Telegram 1. Abrir Telegram y buscar a @BotFather. 2. Enviar `/newbot`, asignar nombre y username (ej: `DonJulioRestoBot`). 3. Obtener el `BOT_TOKEN` proporcionado por BotFather. 4. Registrar el Webhook hacia n8n: ```bash curl -X POST "https://api.telegram.org/bot/setWebhook" \ -H "Content-Type: application/json" \ -d '{"url": "https://tu-n8n.com/webhook/zilliad-telegram-webhook", "allowed_updates": ["message"]}' ``` 5. Enviar mensaje de respuesta con `POST https://api.telegram.org/bot/sendMessage`. --- ## 5. Integración en el Sitio Web del Cliente (Widget Flotante & Embebido) Pegar antes de la etiqueta de cierre `` en cualquier web (WordPress, Shopify, Tiendanube, Webflow, HTML): ```html ``` --- ## 6. Sincronización con CRMs y Bases de Datos - **HubSpot CRM:** Creación de contactos y negocios (deals) vía Private App token (`POST https://api.hubapi.com/crm/v3/objects/contacts`). - **Google Sheets:** Nodo nativo n8n que añade una fila en tiempo real con fecha, cliente, teléfono, canal, interés y transcripción resumida. - **Webhooks Salientes:** Despacho de JSON hacia el ERP interno del cliente con firma HMAC-SHA256 para verificación de autenticidad. --- ## 7. Protocolo de Seguridad, Semáforos en Vivo y Handoff Humano 1. **Detección de Crisis:** Palabras como `estafa`, `denuncia`, `abogado`, `intoxicado`, `desastre`, `ladrones`. 2. **Pausa Inmediata:** El bot se silencia en 0.2s y la base de datos cambia el estado a Semáforo Rojo. 3. **Alerta Instantánea:** WhatsApp urgente al teléfono personal del dueño con el resumen del incidente y botón directo para atender manualmente. 4. **Reactivación:** El operador humano puede responder libremente y reactivar el bot cuando la situación esté resuelta.