Bot WhatsApp automático¶

Atención 24/7 automática

El Bot WhatsApp atiende a tus clientes automáticamente con un menú interactivo. Identifica al cliente por DNI, le muestra su saldo, recibe comprobantes de pago, deriva a tu equipo según el motivo. Funciona en tu mismo número de WhatsApp Business.

Requisitos¶

Requisito	Detalle
Addon Bot WhatsApp	$15/mes — se contrata en my.hybschat.com/cart.php?gid=addons
Sistema ISP	Mikrowisp o WispHub (Wimovil y Wispro no están soportados todavía)
ISP configurado en HybsChat	URL del ISP + token API con permisos de lectura de clientes + facturas + promesas de pago
Inbox WhatsApp en Chatwoot	Conectado a Meta Cloud API (no Twilio ni otros gateways)

Activación¶

Contratá el addon desde tu área de cliente WHMCS.
Configurá tu sistema ISP en my.hybschat.com → Configuración → Sistema ISP (si no lo hiciste todavía).
Andá a la card Bot WhatsApp en tu dashboard. Vas a ver el toggle "Desactivado".
Activá el toggle. El primer setup tarda unos segundos — HybsChat crea automáticamente:
- 4 equipos canónicos en Chatwoot (si no existen)
- Canned response "pagos" para que tus agentes editen las formas de pago
- Webhook outbound desde Chatwoot apuntando al bot
- Vinculación del agent_bot oficial "HybsChat Bot" al inbox WhatsApp
Confirmá los datos Meta: la card muestra si tu inbox tiene phone_number_id, business_account_id y api_key (Meta token) cargados — los toma automáticamente del provider_config del inbox Chatwoot.

Setup idempotente

Si los equipos/canned ya existen con esos nombres, el bot los reutiliza. Podés re-correr el setup sin miedo a duplicados.

Flow del cliente (qué ve tu cliente al chatear)¶

flowchart TD
    A[Cliente escribe Hola] --> B{Bot envía menú principal}
    B -->|1. Soy cliente| C[Bot pide método de identificación]
    B -->|2. Quiero contratar| D[Bot deriva al team Comercial]
    C -->|Cédula| E[Bot pide DNI]
    C -->|Hablar con asesor| F[Bot deriva al team Atención]
    E --> G{Bot busca cliente en tu ISP}
    G -->|Encontrado| H[Bot muestra saldo + menú cliente]
    G -->|No encontrado x3| F
    H -->|1. Cuánto debo| I[Bot responde saldo]
    H -->|2. Dónde pago| J[Bot muestra formas de pago]
    H -->|3. Reportar fallas| K[Bot deriva al team Soporte]
    H -->|4. Hablar con asesor| F
    H -->|5. Enviar comprobante| L[Bot pide foto del comprobante]
    H -->|6. Otra cuenta| E
    L --> M[Cliente sube foto]
    M --> N[Bot reporta pago al ISP + crea promesa + deriva al team Pagos]

📱 Menú principal
Bienvenido al Menú de opciones. Estamos aquí para ayudarte con todo
lo relacionado con nuestros servicios. Por favor elegí una opción:

1️⃣ Soy cliente 👤
2️⃣ Quiero contratar

Si elige "Soy cliente"¶

Identifícate de alguna forma:

· Cédula
· Hablar con un asesor

Si elige "Cédula"¶

Ingresá tu Cédula, DNI, C.I./C.C.

El cliente manda su DNI. El bot busca en tu ISP:

Encontrado: muestra saludo personalizado + saldo + menú de opciones (ver abajo)
No encontrado (intento 1 o 2): le pide otra vez con sugerencia ("revisá si lo escribiste bien")
No encontrado (intento 3): deriva automáticamente a un asesor humano del team Atención

📱 Soy cliente 👤
Selecciona una de las siguientes opciones:

1️⃣ Cuánto debo? 💲
2️⃣ Dónde pago? 💳
3️⃣ Reportar fallas
4️⃣ Hablar con asesor
5️⃣ Enviar comprobante
6️⃣ Otra cuenta ❌

Reporte de pago con comprobante (opción 5)¶

Bot pide foto del comprobante
Cliente envía imagen/PDF
Bot llama a tu API ISP:
- Reporta el pago (queda registrado en tu sistema con forma_pago "bot")
- Crea promesa de pago automática (si está habilitada) que extiende el servicio N días
Bot deriva la conversación al team Pagos con nota privada conteniendo:
- Datos del cliente y factura
- Resultado del upload (OK + task_id, o error)
- Resultado de la promesa (OK hasta fecha límite, o error)
- Link al comprobante adjunto en Chatwoot
Un agente humano valida el comprobante y marca la factura como pagada manualmente.

Por seguridad NO marcamos la factura como pagada automáticamente

El reporte de pago crea solo una promesa (que extiende el servicio temporalmente). La marca de "factura pagada" la hace siempre un humano para evitar fraudes con comprobantes falsos.

Atajos durante el flow¶

Cliente escribe	Bot hace
`#`	Si está en cola esperando asesor: confirma cancelación. Caso contrario: shortcut a derivar al asesor
`cancelar`	Cancela espera de asesor y vuelve al menú principal
Cualquier texto cuando ya está hablando con humano	Bot ignora (el agente toma el control)

Configuración del bot¶

Toda la configuración vive en la card Bot WhatsApp de tu dashboard HybsChat.

Gestión de equipos¶

Los teams agrupan agentes por especialidad. El bot deriva conversaciones según el motivo:

Motivo	Team al que deriva (default)
Hablar con asesor	Atención al Cliente
Reportar fallas	Soporte Técnico
Enviar comprobante	Pagos y Facturación
Quiero contratar	Comercial

Desde el dashboard podés:

Crear nuevos teams (se reflejan en Chatwoot automáticamente)
Renombrar teams existentes
Ver la lista actual

Para agregar/quitar agentes a un team, andá a Chatwoot directamente (ese flujo no está expuesto en HybsChat).

Routing personalizado de teams¶

Si tenés varios teams o querés que el bot derive a un team específico (no el detectado por nombre), elegí el team manualmente desde el dropdown "Routing de teams" en tu dashboard:

💬 Hablar con asesor → team X
🛠 Reportar fallas → team Y
💳 Enviar comprobante → team Z
🛒 Quiero contratar → team W

Si dejás "Auto", el bot busca el team por nombre/keyword y si no lo encuentra, asigna al primer team disponible (no falla silenciosamente).

Promesa de pago automática¶

Cuando un cliente envía su comprobante, podés crear automáticamente una promesa de pago que mantiene su servicio activo por N días mientras un humano valida el comprobante.

Setting	Valor
Activar promesa automática	ON/OFF (default: OFF — recomendado activarlo)
Días de plazo	1-20 días (default: 3)

Cómo funciona la promesa por ISP:

Mikrowisp: usa el endpoint PromesaPago del API. El cliente queda activo por el plazo, factura NO se marca pagada.
WispHub: usa /api/promesa-pago/ con accion=1. Activa el servicio inmediatamente además de registrar la promesa.

Permiso 'Promesas de Pago' en WispHub

Si usás WispHub, tu API key debe tener el permiso "Promesas de Pago" habilitado en el role del usuario API. Sin esto, la promesa falla con HTTP 403 (el reporte de pago sigue funcionando).

Diferencias entre Mikrowisp y WispHub¶

Feature	Mikrowisp	WispHub
Lookup cliente por DNI	✅ `/GetClientsDetails` con cédula	✅ `/api/clientes/?cedula=`
Lookup por teléfono	⚠️ Limitado	✅ `/api/clientes/?telefono=`
Consulta de saldo	✅	✅ via `/api/clientes/{id}/saldo/`
Reporte de pago con foto	✅ legacy `NewTicket` (deprecated)	✅ `/api/facturas/reportar-pago/{id}/` multipart
Promesa de pago	✅ `PromesaPago` (no activa servicio, solo extiende plazo)	✅ `/api/promesa-pago/` con `accion=1` (activa servicio)
Forma de pago "bot" requerida	No	Sí — creala manualmente en WispHub (recomendado)
Marca factura como pagada automática	❌ (intencional, por seguridad)	❌ (intencional, por seguridad)

Cómo se identifica el bot en Chatwoot¶

Los mensajes del bot aparecen en Chatwoot con:

Sender: HybsChat Bot
Type: agent_bot (badge bot 🤖 distinguible del admin humano)
Source_id: setteado al wamid de Meta — Chatwoot reconoce que el mensaje ya fue enviado externamente y no lo reenvía al cliente (evita duplicados)

Esto significa que en tu thread de conversación, el agente humano ve un flujo coherente: cliente → bot → cliente → bot → ... → derivación a humano, todo en el thread público. La info técnica (resultado de uploads, errores, motivos de derivación) queda como private notes que solo el agente ve.

Limitación de Chatwoot UI

Chatwoot Community no renderiza el markdown WhatsApp (*bold*, _italic_) en el panel del agente — vas a ver los asteriscos literales como texto. En el WhatsApp del cliente final sí se renderizan como negrita correctamente porque WhatsApp app interpreta esa sintaxis.

Troubleshooting¶

Activé el toggle pero el bot no responde a los mensajes

Verificá en orden:

Card del bot muestra warnings: si dice "Configurá el sistema ISP", completá la card de Sistema ISP arriba con URL + token.
El inbox de WhatsApp tiene agent_bot vinculado: HybsChat lo hace automático en el setup. Si no, andá a Bot WhatsApp y tocá "Setup ahora".
La conversación entrante NO está asignada a un agente humano: el bot ignora convs con assignee_id setteado. Si un agente respondió manualmente antes, desasigná la conv.
Auto-assignment del inbox está OFF: en Chatwoot inbox settings, el flag enable_auto_assignment debe estar OFF (HybsChat lo configura así automáticamente).

El bot dice 'No encontré ningún cliente con ese DNI'

Verificá:

La cédula que escribió el cliente coincide exactamente con lo guardado en tu ISP
El token de API tiene permisos de lectura sobre clientes
La URL del ISP en HybsChat está sin http:// ni https://
Tu Mikrowisp/WispHub responde el endpoint de búsqueda correctamente (probá manualmente con curl)

El comprobante se subió pero la promesa no se creó

Si es WispHub: tu API key probablemente no tiene el permiso "Promesas de Pago". Habilitalo en WispHub → Configuración → API → Roles.

Si es Mikrowisp: revisá la nota privada en Chatwoot — incluye el error exacto del API.

En ambos casos: el comprobante sí quedó guardado en Chatwoot, podés validarlo manualmente desde la conversación.

El cliente recibió respuestas duplicadas

Bug raro. Causa probable: source_id no respetado por tu versión de Chatwoot. Reportá a [email protected] con captura.

Quiero desactivar el bot temporalmente

Tocá el toggle "Activado" en tu dashboard — pasa a "Desactivado". Las conversaciones existentes quedan asignadas al team al que ya fueron derivadas. Los nuevos mensajes entrantes ya no son procesados por el bot — entran como conv normal sin asignar para que tus agentes los tomen.

Cómo paro de pagar el addon

Cancelá desde tu área WHMCS → Servicios → addon Bot WhatsApp → Solicitar cancelación. La cancelación toma efecto al final del ciclo de facturación actual. El bot queda deshabilitado automáticamente cuando el addon se marca como Cancelled.