MergeOn MCP Server

MCP (Model Context Protocol) server que expone tu cuenta de MergeOn Seller como herramientas y skills para clientes Claude (Claude Desktop, Claude Code, Cursor, Continue, Zed, etc.).

Una vez instalado, puedes pedirle a Claude cosas como:

"Lista mis 10 últimos pedidos sin enviar" "Crea un flow que mande un follow-up 24 h después de un lead nuevo de Instagram" "Actualiza el prompt del agente de ventas para que sugiera el producto X cuando alguien pregunte por talla" "Importa estos 200 contactos de CSV al CRM"

Y Claude usa el MCP para hacerlo directamente contra tu backend de MergeOn.

Tabla de contenidos

1. ¿Qué expone el MCP?
2. Setup en Claude Desktop / Claude Code
3. Tools disponibles (294)
4. Skills incluidos
5. Variables de entorno
6. Desarrollo local
7. Mantenimiento — añadir o modificar tools
8. Publicación a npm

¿Qué expone el MCP?

El MCP ofrece dos tipos de capacidades a Claude:

A. Tools (herramientas ejecutables)

Cada tool es una función que Claude puede invocar. Internamente, el MCP autentica con tu API key (mk_xxx), llama al endpoint correcto del backend de MergeOn (https://api.mergeon.dev por defecto) inyectando tu ecommerce_id, y devuelve el JSON de respuesta a Claude. Claude decide cuándo usar cada tool según el contexto de la conversación.

Cross-tenant (ecommerce_id override): todas las tools aceptan un parámetro opcional ecommerce_id para apuntar a otro tenant (ej. agent_prompts_update({ wpp_prompt_text: "...", ecommerce_id: "57" })). La key de ecommerce 1 (superadmin) puede apuntar a cualquier tenant; una key de implementador puede apuntar a los ecommerces que gestiona; cualquier otra key solo opera sobre el suyo. El backend (authorize_ecommerce_target) valida la propiedad y devuelve 403 si no aplica.

Las 299 tools cubren los principales dominios de MergeOn: CRM, pedidos, productos, conversaciones, flujos de automatización (con catálogo de triggers/conditions/actions descubrible y filtros por reel específico via media_ids), calendario, marketing masivo, analytics legacy, analítica de ventas (revenue, top productos, comparativas y filtros por canal), eventos a Meta CAPI (auditoría + reenvío), nurturing/hidratación de leads, formularios dinámicos con tracking codes + UTMs, videos sociales con auto-tracking y funnel de conversión, webhooks entrantes y salientes (incluido el relay de conversaciones a un agente externo), workers, reparto automático de contactos entre asesores con avisos dirigidos por WhatsApp, admin, configuración del agente IA (prompts + tools), business context (conocimiento dinámico para el agente), plantillas de WhatsApp avanzadas y configuración general del ecommerce.

B. Skills (guías de experto instalables en CLAUDE.md)

Los skills son documentos .md con conocimiento experto que se inyectan en tu CLAUDE.md local vía npx mergeon-mcp skills add <nombre>. A diferencia de las tools, un skill no es ejecutable: es contexto que mejora la calidad de las respuestas de Claude para tareas específicas (escribir prompts del agente, diseñar flows, etc.).

Hoy hay doce skills. Instálalos todos de una vez con npx mergeon-mcp skills add all:

• prompt-creation — experto en redactar el prompt del agente de ventas para WhatsApp/Instagram.
• flows-creation — experto en diseñar flows de automatización (post-venta, pautas, notificaciones, chatbots, flows por reel específico).
• nurturing-creation — experto en hidratación de leads (secuencias multi-touch por stage del CRM).
• templates-creation — experto en plantillas oficiales (HSM) avanzadas con headers media, botones, manual_placeholders.
• forms-creation — forms dinámicos en mergeon.dev/form/{code}: schema, tracking codes con UTMs, atribución a videos, auto-upsert CRM.
• social-tracking — tracking por reel/post: auto-discovery, funnel comments→DM→leads→órdenes, atribución de revenue por video.
• webhooks-usage — experto en integrar sistemas externos (forms, pasarelas, CRMs) con webhooks entrantes.
• sales-analysis — analista de ventas: cómo combinar sales_* para responder bien a "cómo voy".
• meta-events-debug — auditoría de Meta CAPI: por qué no aparece tal venta como Purchase en Events Manager.
• reviews-usage — subir reseñas/testimonios reales (incluidas tarjetas con foto) vía media_upload + reviews_create.
• agent-testing — QA del agente: simular clientes contra la IA en el sandbox y corregir el prompt con la evidencia.
• agent-training — entrenar la IA con los chats reales del negocio en ciclos que se repiten: fallas de producción, banco de casos que crece, regresión completa y salida controlada.

Setup

1. Genera una API key

En tu dashboard de MergeOn Seller: Admin → API Keys → "Generar API Key". Copia la clave (mk_xxxxxxxx). Solo se muestra una vez.

2. Configura tu cliente Claude

Claude Desktop

Edita claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mergeon": {
      "command": "npx",
      "args": ["-y", "mergeon-mcp"],
      "env": {
        "MERGEON_API_KEY": "mk_tu_api_key_aqui"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de MergeOn aparecen en el menú de tools (icono de martillo).

Claude Code

Añade el server con el comando:

claude mcp add mergeon -- npx -y mergeon-mcp -e MERGEON_API_KEY=mk_tu_api_key

Otros clientes (Cursor, Continue, Zed)

Cualquier cliente compatible con MCP-stdio funciona. Apunta al binario npx -y mergeon-mcp y pasa MERGEON_API_KEY como variable de entorno.

3. (Recomendado) Instala los skills

Lo más simple es instalarlos todos de una vez:

cd /ruta/a/tu/proyecto
npx mergeon-mcp skills add all

O uno por uno si prefieres:

npx mergeon-mcp skills add prompt-creation
npx mergeon-mcp skills add flows-creation

Esto añade el contenido del skill a tu CLAUDE.md local, dentro de marcadores <!-- mergeon-skill:nombre --> para futura desinstalación o re-aplicación.

Listar los skills disponibles:

npx mergeon-mcp skills list

Tools disponibles

298 tools organizadas en 28 dominios. Cada nombre corresponde a la cadena exacta que verás en Claude Desktop.

💡 Los dominios marcados con (catálogo descubrible) exponen un tool <dominio>_get_catalog que devuelve los enums, shapes y reglas válidas. Llámalo SIEMPRE antes de crear/modificar para no inventar campos.

CRM (9 tools)

| Tool | Qué hace | |---|---| | crm_list | Lista contactos. Para encontrar a alguien usa q: busca por cualquier identificador que tenga (teléfono, usuario de WhatsApp/Instagram, id del canal) y por nombre, sin saber de qué canal viene. Para acotar una lista: status (lead/warm/hot/cold/sold), city, country, name, source, cellphone, ig_user, wa_user, attended_by, paginación. | | crm_get | Detalle completo de un contacto por id (intereses, calificación, resumen de conversación). | | crm_interests_aggregate | Nuevo en 1.9.0: devuelve todos los valores únicos de interested_in agrupados por categoría (keywords, products, brand_affinity, etc.) en el ecommerce. Ideal antes de añadir tags para evitar duplicados. | | crm_create | Crea contacto. Mínimo: name o cellphone. Opcionales: email, ciudad, país, source, status, ig_user, wa_user, notes. | | crm_update | Actualiza campos de un contacto (PATCH parcial). Útil para cambiar status, corregir el wa_user o reasignar attended_by. | | crm_delete | Elimina contacto permanentemente. | | crm_bulk_import | Importa varios contactos desde CSV (string con cabecera) en una sola llamada. Columnas que se guardan: name, cellphone, ig_id, ig_user, source, city, country. Deduplica por teléfono (o ig_id): los que ya existen se omiten, no se duplican. trigger_flows (default false) dispara el flow crm_created (ej. bienvenida) por cada contacto nuevo. Devuelve {created, skipped, errors, created_ids, error_details}. | | crm_custom_statuses_set | Nuevo en 1.30.0: define los estados de embudo personalizados del tenant (se suman a los base: lead/warm/sold/...). Cada uno {value, label, color?}. La lista enviada REEMPLAZA el set custom previo. Una vez definidos, valen para crm_update/change_lead_status y se pintan en el dashboard. | | crm_tier_rules_get | Nuevo en 1.32.0: devuelve las reglas de segmentación automática por compras (customer_tier_rules) del tenant. | | crm_tier_rules_set | Nuevo en 1.32.0: define las reglas de segmentación automática: cuando las órdenes agregadas de un cliente cruzan un umbral (min_total_spent y/o min_order_count, con window_days opcional), se le asigna set_status. Se evalúa en cada venta y por cron cada hora sobre clientes con ventas recientes. Cuenta TODAS las órdenes (pagadas o no). La lista REEMPLAZA el set previo. Solo promueve (no degrada a un tier ≥). Cada regla: {id, label?, is_active, priority, min_total_spent?, min_order_count?, window_days?, set_status}. |

NPS — Calificación de asesoría (4 tools)

| Tool | Qué hace | |---|---| | nps_config_get | Nuevo en 1.30.0: devuelve la config NPS del tenant (config.extra_config.nps): is_active, delay_hours, scale_max, low_threshold, textos, capture_mode, notify_channel. | | nps_config_update | Nuevo en 1.30.0: actualiza la config NPS (merge parcial). La encuesta se dispara delay_hours después de una venta, pregunta 1..scale_max y si el score ≤ low_threshold pide motivo y notifica al asesor que cerró la venta (notify_channel: whatsapp/dashboard/both). | | nps_summary | Nuevo en 1.30.0: ranking de asesores por NPS: promedio, nº de respuestas y nº de calificaciones bajas por asesor (y IA para ventas cerradas por el bot). | | nps_responses_list | Nuevo en 1.30.0: últimas respuestas NPS (score, motivo, asesor, order_id, status) para inspeccionar calificaciones individuales. |

Pedidos (7 tools)

| Tool | Qué hace | |---|---| | orders_list | Pedidos recientes ordenados por fecha. Filtro last_order (ISO datetime — solo pedidos posteriores). | | orders_get | Detalle completo del pedido por order_id (productos, cliente, pago, tracking). | | orders_create | Crea pedido. Requiere user_name, user_phone, amount. Con products: [{product_id, quantity, name?}] del catálogo, o SIN productos pasando concept (venta libre: mayoreo, servicios, valor variable). Opcionales: address, city, email, provider, observations, status, is_paid, delivery_price. | | orders_update | PATCH parcial de status, payment_status, dirección, monto, notas. | | orders_create_shipment | Crea envío y marca pedido como ready_to_ship. Acepta tracking_number, tracking_url, courier, label_url. | | orders_card_config_get | Nuevo en 1.58.0: botones de la tarjeta de venta del kanban + todo lo que se le puede poner: flows order_card_shortcut del negocio, acciones del panel (guía, Dropi, marcar pagado, cambiar estado, chat, evento Meta), iconos, estilos e integraciones conectadas. configured: false = nunca se personalizó. | | orders_card_config_set | Nuevo en 1.58.0: define los botones de la tarjeta (lista COMPLETA y en orden). kind: 'flow' ejecuta un flow de atajo; kind: 'builtin' dispara una capacidad del panel. Cada botón lleva texto, icono, color y en qué estados aparece. Los botones fijos de "Guía" y "Dropi" salieron del código: ahora se agregan (o no) desde acá. | | orders_export_config_get | Devuelve el mapeo de columnas de exportación CSV (orden, encabezados, separador, fila de encabezados) + available_fields (catálogo de campos del pedido mapeables). Mismo config que usa el botón "Exportar CSV" del dashboard. | | orders_export_config_update | Define cómo se exportan los pedidos a CSV: columns: [{field, header}] (orden = orden de columnas), delimiter (',' ';' o '\t') e include_header. field debe ser una key de available_fields. Persiste por tenant. |

Productos (8 tools)

| Tool | Qué hace | |---|---| | products_list | Catálogo paginado, búsqueda por search (nombre/descripción), brand, sort, limit, offset. | | products_brands_list | Las marcas distintas del catálogo. Es el índice previo a products_list({brand}) y lo que necesita una tienda web que agrupa por marca o proveedor (una página por marca). Vacío en catálogos que se leen en vivo (rol shopify o woocommerce). | | products_get | Detalle por identificator (ID o slug), incluye variantes, imágenes, inventario. | | products_create | Crea producto. Requiere name y price. Opcionales: description, available (pásalo true para publicarlo), brand, metadata, category (string o lista — se envía como lista), discount_price/has_discount, slug, video_url, variants, duration_minutes, capacity. Las imágenes, el stock y el precio por tamaño viven en variants (no hay columna photo_url a nivel producto): cada variante lleva su photo_url, su stock y, nuevo en 1.73.0, su price/discount_price propios para cuando el tamaño cambia lo que se cobra (pizza personal vs familiar, talla XS vs XXL). Sin price, la variante se vende al precio del producto — que es como se comporta todo el catálogo que ya existe. El video sí es de producto (video_url). Servicios agendables (verticales health/services): un servicio es un producto con duration_minutes y capacity; su price es el valor que se reporta a Meta como el del evento Schedule (0 si la consulta es gratuita). Funciona donde el catálogo lo maneja MergeOn (scratch, siigo, shopify_synced); da 403 en las fuentes que se leen en vivo (rol shopify o woocommerce). metadata (nuevo en 1.90.0) es la ficha libre que pinta la TIENDA WEB (pares clave/valor: altura y variedad de un café, estrato y área de un inmueble). El agente NO la ve —lo que el bot deba saber va en description— y ninguna sincronización la pisa. | | products_update | PUT parcial de campos del producto: name, price, description, available, brand, metadata, category, discount_price/has_discount, stock/manage_stock, slug, video_url, variants, duration_minutes, capacity. Pasar variants reemplaza el array completo; es la vía para fijar fotos y precios por variante (price/discount_price propios, nuevo en 1.73.0). video_url es el video de venta que el agente manda por WhatsApp (menos de 14 MB para que se reproduzca dentro del chat). En un producto que vino de una integración, cada campo que cambies acá queda marcado como editado a mano y las sincronizaciones dejan de pisarlo. En servicios agendables, duration_minutes y capacity mandan sobre los defaults del negocio. | | products_delete | Borra un producto para siempre (no hay deshacer: se va la fila con sus variantes, fotos y metadata). Para sacar algo de venta usa products_update({available:false}), que conserva el historial y permite volver a publicarlo con el siguiente lote. Esta es para filas que no debieron existir: duplicados, pruebas, una importación mala. No funciona en catálogos que se leen en vivo (rol shopify o woocommerce). | | products_bulk_update | Aplica los mismos cambios a varios productos a la vez. Útil para subir/bajar precios en masa o (des)activar lotes. En productos que vinieron de una integración, marca los campos como editados a mano igual que products_update, así que las sincronizaciones no los pisan. | | products_bulk_create | Crea MUCHOS productos de una (array products, mismos campos que products_create). Para cargar un catálogo entero sin subir uno por uno. Crea cada uno por separado (una fila mala falla sola sin frenar el resto) y devuelve { total, created, failed, results } con id o error por ítem. |

Conversaciones (4 tools)

| Tool | Qué hace | |---|---| | conversations_list | Lista sesiones (hilos WhatsApp/Instagram) con paginación. | | conversations_get | Mensajes completos de una sesión por session_id. Los salientes traen metadata.origin (ai, flow, nurturing, scheduled, reminder, nps, campaign, human) + metadata.worker (asesor) y metadata.origin_name (flujo/regla). | | conversations_search | Busca texto en mensajes de todas las conversaciones (mínimo 3 caracteres). Filtros: from_user, from_agent. | | conversations_range | Trae todos los mensajes creados entre since y until (ISO 8601), orden cronológico. Para sincronización incremental por ventana de tiempo (ej. cron cada 30 min). |

Flujos / Flows (6 tools + catálogo descubrible)

| Tool | Qué hace | |---|---| | flows_list | Lista todos los flows con id, name, trigger_type, conditions, actions[], is_active, continue_agent, scheduled_at. | | flows_create | Crea flow. Campos: name, trigger_type (enum), actions[] (array de {action_type: payload}), conditions, is_active, continue_agent, is_exclusive, scheduled_at. La descripción de la tool enumera triggers y condiciones válidas por trigger. Nuevo en 1.5.1: ig_comment acepta conditions.media_ids[] y conditions.media_product_type para flows por reel/post específico. Nuevo en 1.8.0: is_exclusive en trigger sold → solo el flow exclusivo más específico corre; los no-exclusivos siempre corren. | | flows_update | PATCH parcial. Re-valida constraints de story_reply/decision_tree/scheduled_send. | | flows_delete | Elimina flow por flow_id y limpia cache de flows. | | flows_execute | Ejecuta flow manualmente con crm/message/order, opcional template_placeholders (overrides de campos manuales para send_template) y opcional template_file_url (override del header image/video/documento del template, ej. guía de envío específica del pedido). Opcional session_id + source para fijar la conversación destino exacta (evita que el canal se re-derive del contacto). Permite ejecutar flows inactivos manualmente. | | flows_get_catalog | Catálogo descubrible: devuelve todos los trigger_types con sus condiciones válidas, todos los action_types con sus payloads, los order_statuses válidos y los {{placeholders}} disponibles (order/crm/message/event/time + aritmética). Llamar antes de diseñar un flow para no inventar triggers/actions. |

Nuevo en 1.63.0 (follows_me): nueva condición de default_message que exige que la persona siga (true) o no siga (false) la cuenta de Instagram. Instagram no tiene webhook de seguidor nuevo —el disparador que usan otras herramientas es una beta privada de Meta, no la API pública— pero sí se puede consultar de a una persona, y solo de quien YA escribió al negocio (Meta exige ese consentimiento). Por eso no sirve en ig_comment: el camino es comentario → DM → responde → ahí se evalúa. Va en AND con las demás condiciones y, si no se puede averiguar, no se cumple. Habilita el patrón "sígueme y te paso el link".

Nuevo en 1.58.0 (botones): nueva action send_buttons — texto + botones de enlace (url) o de respuesta rápida (reply). WhatsApp los manda como mensaje interactive (hasta 3 respuestas rápidas, o 1 enlace como cta_url); Instagram y Messenger como quick_replies. Cuando el cliente toca una respuesta rápida, el tap entra como mensaje normal con su payload, así que se encadena con un flow default_message + la nueva condición button_payload. Sirve también en ig_comment para mandar el DM con botones.

Nuevo en 1.58.0: flows_get_catalog ya no devuelve una copia estática: lee el catálogo del backend (app/flows/catalog.py), la misma fuente con la que se valida al crear un flow. Por cada trigger dice qué acciones sirven de verdad (status: ok o partial si el dato puede faltar), sus condiciones y sus placeholders válidos. Una acción incompatible ahora se rechaza al crear con un mensaje claro, en vez de guardarse y no ejecutarse nunca. Además el trigger order_card_shortcut (botón en la tarjeta de venta) ya se puede usar desde el MCP.

Nuevo en 1.57.0: triggers query_created (el agente creó una consulta) y human_attention (el agente escaló a un humano), más las actions assign_advisor y notify_advisor. Con esto el reparto de asesores y los avisos al equipo dejan de estar hardcodeados: son flows que el negocio edita. Sin flows de esos triggers aplica lo configurado con advisors_notifications_set.

Nuevo en 1.65.0: condición state + actions set_state / clear_state. Le dan memoria a default_message: un flow marca la conversación (normalmente el ig_comment que abre el embudo) y los pasos siguientes exigen esa marca, con TTL. Sin esto una condición de texto es una regla global sobre TODAS las conversaciones del negocio, y un similar_text: "listo" termina contestándole a quien nunca entró al embudo. Ningún paso de un embudo debería filtrar solo por palabra clave.

Nuevo en 1.65.0: action set_interest. Etiqueta al contacto en interested_in.keywords desde el propio flow (merge, sin duplicar y sin pisar lo que ya tenía), sin gastar un turno de IA. Es el campo por el que filtran marketing_send_bulk (interests) y la hidratación (interest_keywords), así que sirve para segmentar después a quien tocó un botón o comentó un reel. No le llega nada al cliente y no abre la ventana de mensajería.

Para escribir flows con recetas y buenas prácticas, instala el skill flows-creation (npx mergeon-mcp skills add flows-creation). El skill ya cubre los 14 triggers y las 21 actions del backend.

Calendario (9 tools)

| Tool | Qué hace | |---|---| | calendar_list | Lista eventos con filtros opcionales: start_date, end_date, event_type (appointment/task/reminder/followup), status, priority. | | calendar_today | Eventos del día. | | calendar_upcoming | Próximos eventos N días (1-90, default 7). | | calendar_resource_availability | Qué espacios reservables (consultorios/salas) quedan libres en una fecha y franja. Cruza citas de MergeOn con el Google Calendar propio de cada espacio. Devuelve available/busy/unknown — lo que cae en unknown no se pudo consultar y NO debe ofrecerse como libre. Requiere espacios configurados con ecommerce_resources_set. | | calendar_get | Detalle de evento por event_id. | | calendar_create | Crea evento. Requiere title y date. Opcionales: time, event_type, duration_minutes, priority, contact_id, description, price (valor de la cita → Meta CAPI Schedule/Lead vía flow appointment_created). | | calendar_update | PATCH parcial. | | calendar_complete | Marca evento como completado. | | calendar_delete | Elimina evento. |

Marketing (3 tools)

| Tool | Qué hace | |---|---| | marketing_rate_limit | Devuelve el tier actual de mensajería WhatsApp y mensajes enviados hoy. Llamar antes de envíos masivos. | | marketing_campaigns | Lista campañas pasadas con stats de delivery. | | marketing_send_bulk | Envía mensaje masivo por WhatsApp/Instagram. Acepta template_name (HSM aprobada, llega a cualquiera) o message_text (texto libre, solo WhatsApp, solo a contactos dentro de la ventana de 24h). Combina con filters (status/city/source/interested_in/attended_by) o users (lista explícita de strings: teléfonos o IG user IDs). |

Analytics legacy (1 tool)

| Tool | Qué hace | |---|---| | analytics_orders | Pedidos en rango first_month–last_month (formato YYYY-MM). Útil para revenue y tendencias. Deprecado en favor de sales_* — mantiene compatibilidad. |

Analítica de ventas (9 tools + catálogo descubrible)

Combinaciones agregadas para responder rápido "cómo van las ventas". El MCP calcula los breakdowns (status / provider / canal / ciudad / día) en memoria a partir de /analytics/orders/. Para guías de uso, instala el skill sales-analysis.

| Tool | Qué hace | |---|---| | sales_get_catalog | Catálogo descubrible: statuses válidos, métricas calculables (revenue, avg_ticket, from_ads_share_count, breakdowns…), workflow recomendado. Llamar antes de cualquier análisis. | | sales_summary | Reporte agregado del rango (last_days o first_month/last_month): revenue, count, avg_ticket, breakdowns por status/provider/ciudad/canal y serie diaria. Acepta filtros only_paid, statuses, only_from_ads. | | sales_top_products | Top productos por unidades / revenue / órdenes distintas. | | sales_by_advisor | Ranking de ventas por asesor (/analytics/orders/by-advisor): cada orden se acredita al asesor que la creó, a IA si la cerró el bot, o Sin asignar. Devuelve [{advisor, is_ai, orders, revenue}]. | | sales_advisor_metrics | Panel completo por asesor (/analytics/orders/advisor-metrics): tiempo de respuesta manual (promedio/mediana), chats atendidos, ventas y conversión del asesor en el rango. | | sales_advisor_metrics_rollup | Nuevo en 1.62.0: precalcula los tiempos de respuesta de los últimos N días (backfill del histórico). Idempotente. Solo hace falta una vez por negocio: desde la mejora, cada respuesta registra su propia espera al enviarse y el cron diario reconcilia el día anterior. Correrlo cuando sales_advisor_metrics reporte response_source 'live' o 'mixed'. | | sales_conversion | Conversión del período (/analytics/orders/conversion): leads creados vs leads que compraron, segmentado por origen pauta (CTWA) vs orgánico. | | sales_ghosted_conversations | Clientes que dejaron en visto (/analytics/orders/ghosted): leyeron el último mensaje de WhatsApp y no respondieron en min_hours. Lista para follow-up/remarketing. | | sales_compare_periods | Compara dos periodos (current vs previous). Si no se pasa el previo, se infiere "mismo tamaño hacia atrás". Devuelve delta_pct. | | sales_orders_in_range | Órdenes crudas en rango (sin agregar). Útil para exportar o revisar casos puntuales. | | sales_recent_orders | Últimas órdenes (/orders/recent) sin agregar. Ideal para "¿llegó la orden de Juan?". |

Eventos a Meta CAPI (9 tools + catálogo descubrible)

Auditoría y backfill de eventos de Conversions API for Business Messaging. Para diagnóstico end-to-end, instala el skill meta-events-debug.

| Tool | Qué hace | |---|---| | meta_events_get_catalog | Catálogo descubrible: tipos de evento (sold/lead_submitted/whatsapp_referral), source CAPI vs DIRECT, señales de verificación (meta_sent, event_created, fbtrace_id), workflow de debugging. | | meta_events_health_check | Composite: verifica config Meta (waba, ads_token, dataset, pixel), cuenta eventos vs órdenes recientes, devuelve next_step. Punto de entrada del diagnóstico. | | meta_events_advertisement_list | Lista eventos advertisement_events con filtros: advertisement_id, event_type, date_from/date_to, paginación. Cada item incluye source, details.fbtrace_id y order_id. | | meta_events_advertisement_get | Detalle completo de un evento por event_id. | | meta_events_advertisements_list | Lista anuncios (/advertisement/) registrados. Mapea advertisement_id → metadata del ad. | | meta_events_order_capi_status | Devuelve TODOS los eventos CAPI de una orden: has_sold_event, sold_event y timeline. Úsalo para "¿Meta recibió la venta X?". | | meta_events_order_capi_preview | Dry-run antes de enviar: busca el whatsapp_referral vinculado al teléfono de la orden (normaliza +/sin-+) y devuelve would_be_source (CAPI vs DIRECT), ad_id, ctwa_clid y referral_event_id. Úsalo cuando una orden de anuncio cae como DIRECT. | | meta_events_orders_pending_capi | Lista órdenes pagadas SIN evento sold registrado. Útil para backfills. | | meta_events_send_order_capi | Reenvía evento Purchase para una orden. Idempotente: si ya existe devuelve already_exists: true. | | meta_events_send_bulk_capi | Reenvía Purchase para muchas órdenes (recibe la lista que devuelve meta_events_orders_pending_capi). |

Eventos a TikTok (6 tools)

Retroalimentación de conversiones a TikTok Ads con Events API 2.0 (event_source: crm). Es el equivalente de Meta CAPI para TikTok y no depende de ninguna beta: empareja la venta con el clic por teléfono y correo del comprador (hasheados con SHA-256), así que funciona igual cuando el anuncio de TikTok abre WhatsApp en vez de un DM. El canal de mensajes de TikTok es otra cosa y sigue esperando la allowlist de Business Messaging.

| Tool | Qué hace | |---|---| | tiktok_status | Si el negocio reporta a TikTok y cómo está configurado. Mira in_test_mode primero: con el test event code puesto, nada cuenta como conversión real — es la causa #1 de "TikTok no me recibe las ventas". Nunca devuelve el token. | | tiktok_connect | Conecta la cuenta con dos datos de TikTok Events Manager: el access token de Events API y el ID de un conjunto de eventos tipo CRM. No valida al guardar (TikTok no expone un "¿este token sirve?"): se prueba con tiktok_test. | | tiktok_config_update | Nombre del evento de compra y de lead, test event code y encendido/apagado. El nombre del evento tiene que ser el mismo al que está optimizada la campaña. Mandar test_event_code vacío es lo que saca al negocio del modo de prueba. | | tiktok_test | Manda un evento ficticio a Test Events. Exige el test event code a propósito: sin él la prueba entraría como conversión real. | | tiktok_send_order_event | Reporta un pedido a mano (backfill). Idempotente: un pedido ya reportado vuelve con skipped_duplicate: true salvo que pases force. | | tiktok_disconnect | Borra las credenciales. Los eventos ya reportados se quedan en TikTok. |

Nurturing / Hidratación de leads (6 tools + catálogo descubrible)

Secuencias multi-touch por etapa del CRM (cold/warm/hot/sold/...). Internamente endpoint /hydration/. Para diseñar secuencias, instala el skill nurturing-creation. v1.13.0: los flows aceptan interest_keywords para segmentar por interés; la IA de WhatsApp etiqueta leads con la tool de bot add_lead_keyword (aparece en agent_tools_get).

| Tool | Qué hace | |---|---| | nurturing_get_catalog | Catálogo descubrible: stages típicos, shapes de las 3 acciones (send_message, send_template, run_agent), best practices de hours_trigger y guardrails (max_activations, ventana de 24h de WhatsApp). | | nurturing_flows_list | Lista todos los flows de hidratación. | | nurturing_flow_create | Crea flow: name, lead_stage, hours_trigger, action, is_active, max_activations, max_activations_window_days, interest_keywords (v1.13.0: filtra el flow a leads con esas keywords en interested_in), send_if_paused (v1.46.0: si true, llega también a contactos pausados con respond=false). | | nurturing_flow_update | PATCH parcial. | | nurturing_flow_delete | Elimina permanentemente. | | nurturing_logs | Log de ejecuciones con lead_name/phone, sent_at, action_text. Útil para auditar disparos reales. | | nurturing_create_sequence | Crea de un solo golpe una secuencia completa (varios flows con misma lead_stage y distintos hours_trigger). Útil para "arma una hidratación 4h/24h/72h/7d". |

Formularios / Forms (11 tools — schema dinámico + tracking codes + UTMs + destino condicional + guardado parcial)

Forms que se renderizan en mergeon.dev/form/{tracking_code}. 1 form → N tracking codes (uno por reel/canal). Submissions auto-crean CRM y atribuyen al video. Skill: forms-creation.

| Tool | Qué hace | |---|---| | forms_get_catalog | Field types válidos, destination_modes, after_submit shapes, ejemplos. Llamar primero. | | forms_list | Lista forms con métricas (total_submissions, total_codes, last_submission_at). | | forms_get | Uno con full schema. | | forms_create | Nuevo form. Field types: text, textarea, email, phone, url, number, yes_no, select, multi_select, checkbox, date. Soporta condicionales (show_if). | | forms_update | PATCH parcial. | | forms_delete | Cascade — borra codes + submissions. | | forms_tracking_codes_list | Codes (los slugs en la URL). Filtra por form_id. | | forms_tracking_codes_create | Bind form → reel/canal con UTMs propias. Code autogenerado si se omite. | | forms_tracking_codes_update | Edita UTMs/label/is_active. | | forms_tracking_codes_delete | Borra code (submissions sobreviven con el code como texto). | | forms_submissions_list | Filtra por form_id, tracking_code o tracked_media_id. | | forms_partials_list | Nuevo en 1.95.0: los que EMPEZARON el formulario y no lo enviaron — qué llevaban escrito, hasta dónde llegaron y su contacto de CRM si ya habían dejado teléfono. Es la lista de remarketing: antes un formulario abandonado no dejaba rastro en el servidor (el renderer guardaba borrador, pero en el navegador del visitante), así que el lead que llegó al campo del teléfono y dudó era invisible. |

Pipeline: forms_create → forms_tracking_codes_create({ form_id, tracked_media_id }) → comparte mergeon.dev/form/{code}. El submit auto-upsertea CRM contact (si hay phone), registra magnet_submitted/lead_captured en el video, dispara webhook saliente (firmado HMAC), y aplica after_submit (mensaje o redirect a Calendly/lo que sea).

Videos / Tracked Media (10 tools — auto-tracking de reels/posts IG)

Videos auto-descubiertos al recibir comentarios. Cada uno acumula métricas (comments, dms_sent, leads, orders, revenue) y eventos de funnel. Para guía completa instala el skill social-tracking.

| Tool | Qué hace | |---|---| | tracked_media_list | Lista videos con métricas agregadas. Sort por last_comment_at (default), total_revenue, total_orders, total_leads, etc. | | tracked_media_top | Top-N por una métrica. Útil para "qué reel vendió más este mes". | | tracked_media_get | Uno solo con métricas. Toma el tracked_media_id interno (no el media_id de Meta). | | tracked_media_funnel | Funnel completo: comments → dms → leads → opens → submissions → orders + tasas de conversión + revenue. | | tracked_media_events | Timeline raw de eventos. Filtrable por event_type. | | tracked_media_label | Pone etiqueta humana ("Reel oferta enero") para que el análisis posterior sea legible. | | tracked_media_update | PATCH parcial: label, permalink, caption, thumbnail_url, media_product_type, product_id. Vincula un producto del catálogo al video (comentarios inyectan ese producto como contexto de la IA y exponen {{product_name}}/{{product_price}} en flows ig_comment); product_id=null desvincula. | | tracked_media_hydrate | Fuerza re-fetch a Meta Graph para llenar permalink/caption/thumbnail si la hidratación inicial falló. | | tracked_media_delete | Destructivo — cascade a todos los eventos. Solo si el usuario lo pide. | | tracked_media_get_catalog | Métricas válidas, event_types canónicos y hint para encadenar con flows_create. |

Pipeline: el webhook entrante de IG crea automáticamente la fila al primer comentario. Para crear un flow específico por reel, usa tracked_media_list → toma el media_id (string numérico de Meta) → pásalo a flows_create({ conditions: { media_ids: [...], media_product_type: "REELS" } }). Flows con media_ids ganan prioridad sobre los ig_comment generales.

Webhooks entrantes y salientes (8 tools + catálogo descubrible)

Dos direcciones, y la dirección la fija el event_type:

• Entrantes — endpoints HTTP que MergeOn expone para que sistemas externos creen contactos, ventas, citas, tickets, reseñas o actualicen leads.
• Salientes — nuevo en 1.79.0: con message_received, MergeOn le POSTea cada mensaje del cliente a un tercero (firmado con HMAC-SHA256 en X-Webhook-Signature) y ese tercero contesta llamando a POST /hitl/text/ con su api_key. Es el relay que deja a un agente externo atender la conversación conservando inbox, CRM y métricas dentro de MergeOn.

Para integrar y debuggear, instala el skill webhooks-usage.

| Tool | Qué hace | |---|---| | webhooks_get_catalog | Catálogo descubrible: 8 event_type válidos (7 entrantes + message_received saliente) con available_fields, reglas de field_mapping y workflow. | | webhooks_list_event_types | Versión raw del catálogo (sin contexto extra). | | webhooks_list | Lista endpoints configurados (con api_key_preview, no la key completa). | | webhooks_get | Detalle de un webhook. | | webhooks_create | Crea endpoint. Devuelve api_key completa solo esta vez. En salientes pide target_url (+ suppress_agent opcional) y devuelve además signing_secret, también una sola vez. | | webhooks_update | PATCH parcial. event_type no es modificable (delete + recreate). | | webhooks_rotate_key | Rota la api_key (la anterior deja de funcionar inmediatamente). En salientes rota también el signing_secret: actualiza al tercero antes o empezará a rechazar los despachos. | | webhooks_delete | Elimina endpoint y su api_key. | | webhooks_logs | Logs de deliveries: raw_payload, mapped_payload, status, error_message, created_record_id. En salientes suma response_status (lo que contestó el tercero) y attempts. Punto de entrada del debugging. |

Perfil de WhatsApp (4 tools)

| Tool | Qué hace | |---|---| | lines_profile_get | Lee de Meta el perfil de empresa de una línea: info, descripción, dirección, correo, sitios web, categoría, foto, nombre visible y estado de un cambio de nombre. | | lines_profile_update | Cambia en Meta solo los campos enviados (info 139, descripción 512, dirección 256, correo 128, máx. 2 sitios con https://, categoría). Admin. | | lines_profile_photo_set | Pone la foto de perfil desde una URL pública (JPG/PNG, máx. 5 MB). Admin. | | lines_display_name_request | Pide a Meta otro nombre visible; queda en revisión y no cambia al instante. Admin. |

Workers (4 tools)

| Tool | Qué hace | |---|---| | workers_list | Lista miembros del equipo con rol, contacto y settings de notificación. Admin/adev. | | workers_create | Crea worker (username, password, role: admin/manager/asesor/adev, opcional full_name, email, phone, notification_enabled, admin_phone para el canal WhatsApp de administración). | | workers_update | Actualiza worker por username: rol, contacto, password, notificaciones o admin_phone (número personal para administrar el negocio por el WhatsApp admin de MergeOn; vacío = desvincular). | | workers_delete | Elimina worker por username. No permite borrarte a ti mismo ni a usuarios adev. |

Asesores — Reparto y avisos (5 tools)

| Tool | Qué hace | |---|---| | advisors_assignment_get | Cupo de reparto configurado: switch, modo (weighted/equal), peso de cada asesor, porcentajes resultantes, orden exacto de turnos, config de avisos y workers disponibles. Llamar antes de cambiar cupos para no borrarle la cuota a nadie. | | advisors_assignment_set | Define quién recibe los contactos nuevos y en qué proporción (pesos relativos: 60/40 ≡ 3/2). Prender/apagar enabled crea/activa (o desactiva) el flow que ejecuta el reparto (crm_created → assign_advisor), que después se edita como cualquier flow. Escribe CRM.attended_by, la llave de la visibilidad por asesor y de los avisos dirigidos. | | advisors_notifications_set | Avisos por WhatsApp al asesor desde el número del negocio (consulta, atención humana, orden nueva) con botones Listo e Ir al chat. target: 'assigned' = solo el asesor del contacto, con fallback para los contactos sin dueño. order_created migra el aviso histórico de orden nueva (all = como siempre, assigned = dirigido, off = lo hace un flow). | | advisors_alert_template_status | Estado en Meta de la plantilla de aviso (APPROVED/PENDING/REJECTED o inexistente). 1.58.0: la plantilla solo se usa cuando el asesor está FUERA de su ventana de 24h; dentro de la ventana el aviso sale como mensaje normal con el botón Ir al chat, sin plantilla. | | advisors_alert_template_create | Crea esa plantilla en la WABA del negocio (utility, 3 variables, quick reply Listo + botón URL Ir al chat con la conversación como sufijo dinámico). 1.58.0: ya se crea sola al activar los avisos y, si falla, en el primer aviso fuera de ventana; esta tool es para forzarla. |

Reparto y avisos son configuración + flows, no lógica fija: assign_advisor y notify_advisor sirven en cualquier flow (sold, lead_status_change, query_created, human_attention…), y la config solo aplica cuando el negocio no tiene flows de ese trigger.

Custom Tools (6 tools)

| Tool | Qué hace | |---|---| | custom_tools_list | Lista las herramientas con código Python del tenant (código, parámetros, estado, último error). | | custom_tools_get | Trae una custom tool por id con su código completo. | | custom_tools_create | Crea una tool ejecutable por el bot de ventas. El código define run(params, context) y corre en sandbox aislado (red permitida, sin credenciales de MergeOn, timeout duro). | | custom_tools_update | Update parcial: código, descripción, parámetros, timeout o is_active. Llega al bot en ≤1 min. | | custom_tools_delete | Elimina la tool definitivamente (preferir is_active=false para solo apagarla). | | custom_tools_test | Ejecuta la tool en el sandbox con params de prueba → {ok, output, error, duration_ms}. Correrla SIEMPRE tras crear/editar. |

Admin (20 tools — superadmin ecommerce_id=1 o implementador)

| Tool | Qué hace | |---|---| | admin_ecommerces_list | Lista ecommerces. Superadmin: todos. Implementador: solo los que gestiona. Los escondidos salen solo con include_hidden; tag acota a una etiqueta del panel. | | admin_ecommerce_hide | Superadmin: saca un negocio del panel de MergeOn (o lo devuelve). Es cosmético: el negocio sigue vendiendo y su dueño lo ve igual. | | admin_ecommerce_tags_set | Superadmin: pone las etiquetas del panel de un negocio (implementado, seguimiento, supervision, ia_pendiente). Se manda la lista completa; van varias a la vez. | | admin_ecommerce_create | Crea un ecommerce + su worker admin. Con key de implementador queda bajo su propiedad; superadmin puede pasar implementer_id para asignárselo a uno. 1.45.1: email es opcional (si se omite, el admin entra con el username derivado del nombre del negocio). | | admin_ecommerce_update | Nuevo en 1.45.0: actualiza campos core de cualquier ecommerce: paid (marcarlo como pagado), active, name. Superadmin. | | admin_subscription_get | Nuevo en 1.45.0: suscripción de un ecommerce concreto (plan, status, periodo). Superadmin. | | admin_subscription_create | Nuevo en 1.45.0: crea una suscripción manual para un ecommerce (409 si ya existe). Para facturación manual usar preapproval_id sintético tipo manual_<negocio>_<fecha>. Superadmin. | | admin_subscription_update | Nuevo en 1.45.0: PATCH parcial de la suscripción (status, plan_id, payer_email, periodo). status: "canceled" la cancela. Superadmin. | | admin_ecommerce_set_trial | Otorga/extiende la prueba gratuita: trial_ends_at = now + days (days=0 la quita). Con trial vigente el negocio opera como pagado. Superadmin. | | admin_ecommerce_set_implementer | Solo superadmin: marca/desmarca un ecommerce como implementador (is_implementer) y/o asigna su dueño (implementer_id, null para desasignar). | | admin_whatsapp_link | Solo superadmin (1.65.0): vincula la WABA + número de un cliente a un ecommerce (sin registrar en Meta). Un implementador recibe 403: conecta a su cliente mandándole el link de conexión, y mueve los suyos con admin_portfolio_*. | | admin_whatsapp_disconnect | Desconecta WhatsApp de un ecommerce (no borra el ecommerce). 1.65.0: el número de un cliente solo lo suelta el propio negocio o MergeOn; el implementador recibe 403 salvo que el número sea de su portafolio. | | admin_portfolio_numbers_list | Nuevo en 1.65.0: números de tu propio portafolio de Meta (demos y operación propia), con el negocio que usa cada uno o Libre. Devuelve además portfolio: los demás números de las WABAs que ya conectaste. El alta se hace por Embedded Signup en el dashboard (Integraciones → Mi portafolio comercial). | | admin_portfolio_number_assign | Nuevo en 1.65.0: conecta un número propio a un negocio tuyo que esté sin WhatsApp. 409 si el negocio ya tiene número o si este sigue en uso en otro. Un número atiende a un negocio a la vez. | | admin_portfolio_number_release | Nuevo en 1.65.0: libera un número propio del negocio que lo usa y lo devuelve al pool. | | admin_subscriptions_list | Suscripciones con filtros status y plan. Solo superadmin. | | admin_prompts_get | Prompts del agente IA de un ecommerce concreto. Solo superadmin. | | admin_prompts_update | Actualiza prompts del agente IA de un ecommerce. Solo superadmin. | | admin_channel_conversations_list | Nuevo en 1.56.0: conversaciones de los dueños de negocio con el asistente de MergeOn por el número de administración: una por worker con admin_phone, ordenadas por actividad, con preview del último mensaje. Solo lectura. | | admin_channel_conversation_get | Nuevo en 1.56.0: hilo completo de un cliente con el asistente admin (orden cronológico), por worker_id. Solo lectura. |

Agentes del negocio — Registro (11 tools)

Un agente es un prompt con nombre propio. Los canales (WhatsApp, Instagram, Messenger, comentarios) y las tareas (lectura de imágenes, remarketing por estado del lead) son usos que se le asignan. El mismo agente puede atender varios usos, y un negocio puede tener tantos agentes como quiera.

| Tool | Qué hace | |---|---| | agents_list | Lista los agentes del negocio con los usos que atiende cada uno. | | agents_get | Un agente por id, con su prompt_text completo y sus usos. | | agents_create | Crea un agente (nombre, prompt, descripción) y opcionalmente lo pone a trabajar en una lista de usos. | | agents_update | Edita un agente. Mandar usages REEMPLAZA el set completo de usos; omitirlo deja las asignaciones intactas. | | agents_delete | Borra un agente. Los usos que atendía quedan sin agente (caen al fallback del canal o dejan de responder). | | agents_usages_get | Todos los usos del sistema y quién atiende cada uno. resolved_from: assigned | fallback | legacy | empty. | | agents_usage_assign | Apunta un uso a un agente (o agent_id: null para desasignarlo). Un uso tiene exactamente un agente. | | experiments_list | Los experimentos del negocio, activos y pausados, con sus variantes, pesos y contactos fijados. | | experiments_create | Crea un experimento sobre un canal: reparto A/B por pesos, o prueba dirigida (peso 0 + pinned_contacts). | | experiments_update | Edita variantes, pesos, fijados, ventana o on/off. variants REEMPLAZA la lista completa. | | experiments_delete | Borra el experimento. Los contactos ya asignados conservan su variante y las ventas siguen atribuidas. |

Cadena de fallback entre canales: messenger → instagram → whatsapp. Si un canal no tiene agente propio, hereda el del siguiente en la cadena.

Experimentos: A/B vs dirigida. Un experimento apunta a un canal y reparte sus contactos entre 2+ variantes, donde cada variante es un agente entero. Dos formas de usarlo:

• Reparto A/B — todas las variantes con peso ≥ 1. El contacto cae de forma determinista (sha256 de su identificador) y la variante se congela en el CRM la primera vez, así la venta se atribuye aunque llegue semanas después.
• Prueba dirigida — el control en peso 1, la variante nueva en peso 0 y sus pinned_contacts con los teléfonos o usuarios de IG a probar. Solo esos contactos ven el agente nuevo. Los fijados mandan sobre el reparto y sobre una variante ya congelada, así que sirven para mover a alguien a la rama de prueba a mitad de camino.

Los resultados de las dos salen en sales_by_variant (órdenes, revenue, contactos y conversión por variante).

Agente IA — Simulación de clientes (3 tools)

Hablar con la IA del negocio haciéndose pasar por cliente, sin tocar a nadie real. La sesión lleva prefijo test: → no sale a Meta, no crea CRM, no dispara flows ni CAPI, y el agente corre con tools de solo lectura. Para el ciclo completo de prueba y corrección instala el skill agent-testing. Para entrenarla con los chats reales del negocio, en vueltas que se repiten, instala agent-training.

| Tool | Qué hace | |---|---| | agent_test_chat | Un turno de cliente simulado contra el agente del canal (whatsapp/instagram). Devuelve la respuesta de la IA y el session_id. Con persona (slug) abre un cliente simulado aparte, con historial propio: así se corren muchos clientes distintos contra el mismo prompt sin que se pisen. Sin persona, usa la sesión única del botón del dashboard. | | agent_test_sessions_list | Las conversaciones simuladas del negocio: session_id, número de mensajes y fecha del último. La transcripción se lee con conversations_get. | | agent_test_session_reset | Borra el historial de una persona para repetirla limpia después de cambiar el prompt. Solo toca sesiones test:. |

Agente IA — Configuración (15 tools)

⚠️ Los tools agent_prompts_* son la API anterior al registro de agentes. Siguen funcionando (escriben en el agente que atiende ese canal), pero para crear o reasignar agentes usa el dominio de arriba.

| Tool | Qué hace | |---|---| | agent_plan_get | Plan del usuario, flag B2B, paid, can_access_agents (edición completa: rol + plan), can_manage_tools (gestión de capacidades; gating mínimo: paid), available_tool_names (cae al catálogo completo si el plan no restringe) y selected_tool_names. Útil antes de editar agente para saber qué se puede tocar. | | agent_prompts_get | Prompts del agente: wpp_prompt_text, image_prompt, ig_prompt_text, ig_comment_prompt_text, remarketing_prompt_text y prompts por etapa (cold/warm/hot/sold_prompt). | | agent_prompts_update | Crea o actualiza prompts. Manda solo los campos a cambiar. Channel-specific: wpp_prompt_text, ig_prompt_text, ig_comment_prompt_text. | | agent_prompts_generate | Genera prompts optimizados con IA a partir de un cuestionario estructurado (business_name, business_description, faq, hours, shipping/return policies, payment_methods, catalog, tone). Devuelve borrador para guardar luego con agent_prompts_update. | | agent_prompts_delete | Borra la configuración de prompts. El agente cae a defaults hasta recrearla. | | agent_tools_get | Tools del bot disponibles por plan, tools seleccionadas y si hay selección custom guardada. | | agent_tools_update | Actualiza la lista de tools habilitadas. Recibe selected_tool_names: string[] (debe ser subset de available_tool_names). | | agent_model_get | Estado de proveedores de IA BYO (openai/anthropic/gemini/deepseek), recursos de Azure configurados, catálogo de modelos y selección activa para el trabajo pedido. capability: chat (responder, default), transcription (notas de voz) o vision (imágenes). supports_capability: false = ese proveedor no hace ese trabajo. provider: "default" = hereda. scope: "clients" lee la config que un implementador aplica a los negocios que gestiona. | | agent_model_set | Elige proveedor y modelo para un trabajo (capability). Proveedores no-default requieren su credencial conectada; en azure el model es el deployment y se elige el recurso con azure_credential_id. Acepta scope. | | agent_provider_key_set | Guarda la API key propia del tenant para openai/anthropic/gemini/deepseek. Si no había proveedor seleccionado, este queda activo con su modelo default. Azure no va aquí: usa azure_credential_create. Acepta scope. | | agent_provider_key_delete | Elimina la API key de un proveedor. Si era el activo, la selección vuelve a heredar del implementador. Acepta scope. | | azure_credential_create | Agrega un recurso de Azure OpenAI (label + endpoint + api_key + deployment + api_version). Un tenant puede tener varios. Si es el primero y no había proveedor elegido, azure queda activo. Acepta scope. | | azure_credential_update | Edita un recurso de Azure. Omitir api_key conserva la guardada. Acepta scope. | | azure_credential_delete | Elimina un recurso de Azure. Si era el que estaba en uso, el ámbito vuelve a heredar del implementador. Acepta scope. |

Scope clients (solo implementadores): las credenciales quedan en columnas aparte de las del negocio propio y aplican, como fallback, a todos los ecommerces cuyo implementer_id apunte al implementador. Un negocio con key propia siempre usa la suya.

No hay modelo de plataforma. La cadena es: credencial propia del negocio → credencial de clientes de su implementador → error. Un negocio sin ninguna de las dos deja de responder, para que todo consumo tenga dueño explícito.

Azure va aparte porque necesita key + endpoint + deployment + api-version juntos y admite varios recursos por ámbito: se administra con las tools azure_credential_* y se referencia desde agent_model_set.

Tres trabajos, tres configuraciones. Responder, transcribir notas de voz y leer imágenes se eligen por separado con capability, porque los proveedores no son intercambiables: Anthropic no hace speech-to-text y DeepSeek no hace ni audio ni imágenes. Si un trabajo queda en default, hereda el proveedor de chat siempre que ese sepa hacerlo; si no, ese trabajo queda sin servicio. | agent_password_verify | Verifica la contraseña del worker autenticado. Útil como gate antes de operaciones sensibles del agente. |

Para escribir prompts con la calidad y estructura recomendada, instala el skill prompt-creation.

Business Context — Conocimiento dinámico del agente (4 tools)

Entradas (title, content) que el agente lee como conocimiento adicional cuando responde. Ideales para promos activas, horarios especiales, políticas estacionales, info de stock crítica, etc.

Galerías de fotos auto-sincronizadas: al crear/actualizar una entrada con photos (array de URLs), el backend genera y mantiene en sync un flow llamado Galeria: <title> cuya única acción es send_images con esas fotos. El agente recibe la marca 📷 Galería disponible en su contexto y puede invocar ese flow con execute_flow_by_name. Editar las fotos actualiza el flow; vaciarlas lo borra; renombrar el title lo renombra; desactivar el contexto lo desactiva.

| Tool | Qué hace | |---|---| | business_context_list | Lista todas las entradas (activas e inactivas). | | business_context_create | Crea entrada (title, content, is_active default true, opcional photos[]). Markdown soportado en content. Si photos no vacío → auto-crea flow Galeria: <title>. | | business_context_update | PATCH parcial. Cambios en title/photos/is_active se reflejan automáticamente en el flow asociado. | | business_context_delete | Borra entrada permanentemente y su flow asociado. Prefiere update con is_active:false si pudieras reusarla. |

Plantillas WhatsApp (5 tools + catálogo descubrible)

Plantillas oficiales (HSM) y libres internas. Para creación avanzada (headers media, botones, manual_placeholders), instala el skill templates-creation.

| Tool | Qué hace | |---|---| | templates_get_catalog | Catálogo descubrible: component_types, header_formats, button_types, language_codes, reglas de NAMED placeholders, ejemplos por tipo de bloque. | | templates_list | Lista plantillas con status, language, content y components. | | templates_get | Plantilla por identifier (ID o name con by_name: true). | | templates_create | Crea plantilla. Schema real: name (snake_case), content (BODY con {{nombre}} NAMED), language, placeholders (Dict[str, str] con samples), manual_placeholders ([{key, type, label?}]), components (HEADER/FOOTER/BUTTONS), file_url + mime_type para header media, official (true → submit a Meta). | | templates_update | PATCH parcial. ⚠️ Plantillas APPROVED no se reaprueban: crea otra con name_v2. | | templates_delete | Borra plantilla en MergeOn (no en Meta). |

Nuevo en 1.58.0: el header de media ahora respeta el mime_type (video y documento ya no se mandaban como imagen) y el título de texto (HEADER format TEXT) sí se envía a Meta cuando la plantilla no lleva archivo — antes se descartaba en silencio. button_types quedó en los dos que el backend realmente envía: URL y QUICK_REPLY.

Salón y operación (14 tools — mesas, reservas, cocina, caja e insumos)

Para negocios que atienden en espacios físicos. Las pestañas correspondientes solo aparecen si el negocio activó las capacidades tables, kitchen, shifts o inventory — ver ecommerce_capabilities_set.

| Tool | Qué hace | |---|---| | salon_get | El plano: zonas y mesas, en un solo viaje. | | salon_availability | Qué mesas están libres AHORA y por qué las ocupadas lo están. Se calcula cruzando pedidos en producción y reservas que solapan — no se le cree a la columna status, que es lo que alguien dejó marcado a mano y se desactualiza en minutos. Devuelve unavailable_reason (order/reservation/merged/inactive) porque para quien está sentando gente no es lo mismo una mesa a media comida que una guardada para una reserva. | | salon_zone_create | Crea una zona (terraza, salón, barra) con su precio de separación. | | salon_table_create | Crea una mesa. capacity es cuánta GENTE cabe, no cupos por sesión. Sin precio propio, cobra el de su zona. | | salon_tables_merge | Une mesas para un grupo grande. Una mesa no puede ser hija y principal a la vez: si la principal venía unida a otra, se suelta primero. | | reservations_list | Las reservas, por rango o por estado. Solo pending y confirmed ocupan mesa. | | reservations_availability | Si se puede reservar a esa hora y qué mesa quedaría. Devuelve las dos negativas por separado: "no reservamos hoy" y "no queda mesa" son cosas distintas. Las reglas de tiempo salen de las booking_rules que el negocio ya usa para sus citas. | | reservations_create | Reserva. Sin table_id, el servidor elige la mesa más ajustada — sentar a dos en la de ocho pierde la grande para el grupo que llega después. Sin amount, cobra el precio de la mesa o el de su zona. | | kitchen_board | Lo que está en producción, lo más viejo primero. Con station, cada pantalla ve solo lo suyo. Lo entregado sale del tablero. | | shift_current | El turno abierto y cuánto efectivo DEBERÍA haber en el cajón ahora. Solo cuenta lo pagado en efectivo: contar una transferencia deja un faltante fantasma en cada cierre. | | shift_close | Cierra contando. El arqueo queda congelado en la fila: si mañana cambia la fórmula, el cierre de ayer sigue diciendo lo que se firmó ayer. | | supplies_list | Insumos y cuánto queda. Con only_low, solo lo que hay que comprar. | | supplies_adjust | Suma o resta stock por delta, que es como se mueve de verdad. Nunca baja de cero. | | sales_by_person | Cuánto vendió cada quien, desde sold_by. No hay cifra de "mesero" aparte a propósito: quien toma el pedido en la mesa ES quien cierra la venta. Lo de la IA va aparte. |

Ecommerce (31 tools)

| Tool | Qué hace | |---|---| | ecommerce_get | Configuración del ecommerce, incluido el bloque config (country, currency, store_address). Default: el tuyo. | | ecommerce_update | PATCH del registro principal (name, active, paid, source, shop, billing_provider). No acepta country/currency/store_address (esos van en ecommerce_config_update). | | ecommerce_config_update | PATCH del bloque escalable: country (ISO-3166 alpha-2, default para normalizar teléfonos), currency (ISO-4217, se inyecta en órdenes nuevas) y store_address. | | ecommerce_worker_visibility_set | Nuevo en 1.30.0: define qué ven los asesores en el dashboard. chats y attention aceptan all (ven todo), own (sus asignados + los sin asignar) o strict (SOLO sus asignados — aislamiento total). Admin/manager siempre ven todo. | | ecommerce_agent_debounce_set | Nuevo en 1.38.0: ajusta los segundos que el agente espera tras el último mensaje del cliente antes de responder (debounce, extra_config.agent_debounce_seconds). Menor = respuesta más rápida; mayor = agrupa mensajes troceados. Clamp 0-30, default 5. Afecta directamente el tiempo de respuesta del bot. | | ecommerce_agent_reasoning_set | Nuevo en 1.39.0: nivel de razonamiento del modelo (solo GPT-5, extra_config.agent_reasoning_effort): medium es el default normal; minimal/low responden mucho más rápido; high razona más a costa de latencia. La mayor palanca sobre el tiempo de respuesta del bot. Default medium. | | ecommerce_message_retention_set | Nuevo en 1.42.0: define cuánto tiempo se conservan los chats antes de la limpieza diaria (extra_config.message_retention). Plazos separados por tipo de contacto: normal_days (sin compra ni cita), purchased_days (con orden), scheduled_days (con cita agendada). Solo borra los mensajes más viejos que el plazo; si el cliente compró Y agendó, aplica el plazo más largo. Defaults 90 / 270 / 270. Topes duros: normal 1095 (3 años), compras/citas 1825 (5 años) — el backend recorta cualquier valor mayor. | | ecommerce_schedule_set | Nuevo en 1.46.0: horario de actividad del negocio (extra_config.agent_schedule). Con enabled calcula si la hora actual (en timezone, default America/Bogota) cae en alguna windows (days 0=Lun…6=Dom, start/end 'HH:MM', admite cruzar medianoche). FUERA de horario, 3 gates configurables deciden qué se apaga: gate_agent (default true, silencia el agente), gate_flows (también detiene los flows), gate_hydration (también detiene la hidratación). El mensaje y el CRM siempre se guardan. Merge parcial seguro (lee y mezcla el schedule actual). | | ecommerce_resources_set | Nuevo en 1.52.0: define los ESPACIOS reservables del negocio (consultorios, salas, cabinas) en extra_config.resources. Es lo que permite responder "qué consultorio está libre a las 2pm" en vez de solo "el negocio está ocupado": dos citas a la misma hora son válidas en espacios distintos. Cada espacio lleva id corto y estable, name, calendar_id de Google propio (sin él solo cuentan las citas de MergeOn, no lo que el equipo agenda a mano) y services (vacío = uso mixto). Reemplaza la lista completa; [] desactiva el agendamiento por espacio. Se consulta con calendar_resource_availability y el bot lo usa con la tool check_resource_availability. | | ecommerce_booking_rules_get | Nuevo en 1.53.0: lee las barreras de agendamiento del negocio (extra_config.booking_rules). Úsala para diagnosticar un negocio que reporta citas dobles o duplicadas antes de tocar nada. Devuelve los defaults (desactivado) si nunca se configuraron. | | ecommerce_booking_rules_set | Nuevo en 1.53.0, ampliado en 1.54.0: barreras DURAS de agendamiento que el agente de IA no puede saltarse (extra_config.booking_rules). Sin ellas, lo único que evita que la IA meta cuatro clientes en la franja de las 4:30 es que se acuerde de llamar check_available_slots y le haga caso — una sugerencia del prompt, no una regla. Se validan en el servidor ANTES de escribir la cita. Aplican SOLO a la IA: el equipo humano sigue pudiendo sobreagendar desde el dashboard. Campos: max_per_slot (citas en la misma hora exacta), max_per_hour (2:00 y 2:30 cuentan juntas, 0 = sin tope), max_per_day, allow_same_day (false = nunca hoy, tampoco al reprogramar), min_notice_hours, max_days_ahead, one_active_per_contact (le mueve la cita que ya tiene en vez de crear otra), duplicate_window_minutes (reintento de la IA sobre la misma cita → devuelve la existente en vez de duplicarla), default_duration_minutes (con esto el motor detecta solapes REALES: sin duración, una cita de 2:00 de una hora y otra de 2:30 parecían franjas distintas), allow_parallel_services (si dos servicios DISTINTOS pueden ocupar la misma franja; false = agenda de un solo profesional) y max_per_contact_per_day. Ampliado en 1.99.0: max_per_slot_by_weekday (cupos según el día de la semana de la cita, reemplaza el cupo del servicio), weekday_capacity_from (fecha de cita desde la que rige) y calendar_busy_capacity (cupos que deja un compromiso propio del Google Calendar, como una audiencia; las citas de MergeOn sincronizadas no cuentan; null = bloquea la franja como siempre). Los cupos y la duración de cada servicio se fijan en el catálogo con products_update y pisan estos defaults. Merge parcial seguro. | | ecommerce_delivery_zones_get | Nuevo en 1.80.0: las zonas de reparto y su tarifa. Para diagnosticar un agente que cotiza distinto a dos clientes del mismo barrio — eso pasa cuando no hay zonas y el modelo se inventa el número. | | ecommerce_delivery_zones_set | Nuevo en 1.80.0: zonas de domicilio con tarifa. Cada zona lleva name, price, aliases (los barrios que caen en ella, que es lo que deja al age