Las Habilidades de Conversación son las acciones discretas y ejecutables que el chatbot de un tenant puede realizar en nombre de un contacto. Cada servicio registra sus habilidades con el servicio de Comunicaciones, que enruta los mensajes entrantes de WhatsApp o correo a la habilidad apropiada según el menú de conversación activo, el flujo o las frases de entrenamiento.
Las habilidades se identifican mediante un nombre completamente calificado con la forma <servicio>.<nombre_habilidad> (por ejemplo finance.ar_balance). El conjunto activo de habilidades disponibles para un tenant depende de qué módulos del Portal estén habilitados.
graph LR
USER[Contacto vía WhatsApp / Correo] --> COMM[Despachador de Comunicaciones]
COMM --> AUTH{Verificar llamante}
AUTH -->|no verificado| FLOW[Flujo de captura de leads]
AUTH -->|teléfono coincide / contacto confirmado| SKILL[Invocar endpoint de habilidad]
SKILL --> SVC[Manejador del servicio]
SVC --> RESP[Respuesta formateada]
RESP --> USER
- Un contacto envía un mensaje por WhatsApp o correo.
- El despachador resuelve al llamante a un Socio de Negocio o Prospecto.
- Según el Menú de Conversación activo o el Flujo de Conversación, se selecciona una habilidad.
- El despachador invoca el endpoint interno de la habilidad en el servicio propietario.
- El servicio devuelve una respuesta localizada que se envía al contacto.
Las páginas Constructor de Menú de Conversación y Flujos de Conversación (en Comunicaciones) permiten al tenant elegir qué habilidades se exponen y en qué orden.
Cada habilidad declara el nivel mínimo de verificación que un llamante debe tener para invocarla.
| Nivel | Significado | Uso típico |
|---|
| No verificado | El llamante es anónimo; el sistema no tiene coincidencia con un Socio de Negocio ni un Contacto. | Habilidades de captura de leads (crear prospecto, crear oportunidad inicial). |
| Teléfono coincide | El número de teléfono del llamante mapea a un Socio de Negocio conocido. | Habilidades que actúan sobre el SN coincidente sin requerir confirmación de identidad. |
| Contacto confirmado | El llamante se ha identificado y la identidad del contacto está confirmada contra el SN. | Predeterminado para consultas de autoservicio (saldo, facturas, tickets). |
Todas las habilidades orientadas al usuario soportan WhatsApp y correo salvo cuando se indique lo contrario. Las habilidades internas las invoca únicamente el despachador y nunca se exponen directamente al contacto.
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
bp.resolve_by_phone | Resuelve el teléfono del llamante WhatsApp/correo a un SN y contacto. Interna. | phone | Teléfono coincide | — |
bp.resolve_by_name | Resuelve un nombre de empresa de texto libre a un ID de SN. Interna. | name (≥ 3 caracteres) | Teléfono coincide | — |
bp.account_summary | Resumen compacto de cuenta — nombre, estado, saldos, contacto principal, industria. | bp_id, language | Contacto confirmado | Sí |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
finance.ar_balance | Saldo C/C abierto con desglose de antigüedad (actual, 1-30, 31-60, 61-90, 90+ días). | bp_id, language | Contacto confirmado | Sí |
finance.invoice_list_open | Lista hasta 5 de las facturas C/C abiertas más recientes del SN del llamante. | bp_id, language, limit (1-10) | Contacto confirmado | Sí |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
commerce.quotation_list_recent | Lista hasta 5 Cotizaciones de Venta recientes — número, monto, estado, fecha. | bp_id, language, limit (1-10) | Contacto confirmado | Sí |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
items.search | Búsqueda de ítems en texto libre mediante el índice universal de búsqueda. | query, language | Contacto confirmado | Sí |
items.stock_check | Busca un ítem por código o nombre y devuelve el total de existencias disponibles. | query, language | Contacto confirmado | Sí |
items.find_by_code | Búsqueda exacta por item_code (insensible a mayúsculas). | code, language | Contacto confirmado | Sí |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
crm.create_deal | Crea una oportunidad CRM para un SN o prospecto. Se almacena con una etiqueta de producto opcional. Interna — invocada desde flujos de captura de leads. | bp_id, title, product?, amount (≥ 0), currency (predeterminado USD) | No verificado | — |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
prospects.create_or_find | Busca un prospecto por teléfono, o crea un nuevo prospecto cuando no hay coincidencia. Devuelve el prospect_id. Interna — invocada desde flujos de captura de leads. | name, phone, email?, company? | No verificado | — |
| Habilidad | Descripción | Parámetros | Verificación | Menú |
|---|
projects.status_summary | Vista general del portafolio de proyectos activos del llamante. | bp_id?, since?, language (es / en), open_task_limit? | Contacto confirmado | Sí |
| Habilidad | Descripción | Parámetros | Verificación | Canal | Menú |
|---|
support.create_ticket | Crea un ticket de mesa de servicio desde WhatsApp. El orquestador prellena bp_id. | subject, description, priority (low / normal / high / urgent), bp_id | Teléfono coincide | Solo WhatsApp | — |
support.get_ticket_status | Estado, prioridad y última actualización de un ticket por número (por ejemplo SD-00012). | ticket_number | Contacto confirmado | Todos | — |
support.list_my_tickets | Últimos 5 tickets del llamante, ordenados por actualización más reciente. El orquestador prellena bp_id. | bp_id | Contacto confirmado | Todos | — |
Las habilidades de la Fase 1 declaran una lista required_permissions vacía. La autorización se hace cumplir mediante el alcance del tenant (una habilidad solo puede ver datos dentro del tenant del llamante) y el alcance del SN (las habilidades de lectura están limitadas al Socio de Negocio coincidente del llamante). La validación de permisos por rol se reserva para futuras habilidades que realicen acciones de escritura fuera del alcance del propio llamante.
- Cada servicio registra sus habilidades al inicio con el backend Core. Comunicaciones obtiene el registro activo por tenant.
- La ruta del endpoint de una habilidad se valida contra una lista permitida con la forma
/api/internal/<servicio>/skills/<nombre>.
- Cuando una habilidad se retira o un tenant deshabilita un módulo, Core publica un evento
core.chat_skills.changed y Comunicaciones refresca su caché.
- El despachador revalida la disponibilidad de la habilidad en el momento de la invocación, por lo que una entrada de menú obsoleta no puede alcanzar una habilidad retirada.
- Las respuestas de las habilidades siempre se localizan según el parámetro
language, que el despachador deriva del idioma preferido del contacto.
- Las habilidades expuestas en menú se ordenan según la posición de menú declarada en el registro. El tenant puede reordenarlas, ocultarlas o renombrarlas mediante el Constructor de Menú de Conversación.
- Las habilidades internas (nivel de verificación No verificado sin posición de menú) nunca son seleccionables desde un menú — un flujo las invoca programáticamente.