API y Desarrolladores

Visión general de API y Desarrolladores

Visión general Conversa Labs ofrece una API REST, herramientas MCP para agentes gobernados, webhooks en tiempo real, un SDK de Dashboard Apps para contexto incrustado seguro, un SDK de Custom Scripts para extender interfaces y eventos por módulo para reaccionar a cambios. Requisitos previos - Una cuenta con permiso para generar tokens de API. - Conocimientos básicos de HTTP/JSON. Paso a paso 1. Genera un token de acceso en la configuración de tu perfil/cuenta. 2. Llama a la API REST autenticando con el token. 3. Configura webhooks para recibir eventos en tu endpoint. 4. Usa Custom Scripts para personalizar el dashboard, el portal y el widget. 5. Usa el SDK V2 de Dashboard Apps para una app incrustada limitada y REST o MCP para administrar sus instalaciones nativas. Configuración y opciones - Tokens: por usuario/cuenta, con alcance de acceso. - Webhooks: suscripción a eventos por bandeja/cuenta. - Custom Scripts: JS/CSS inyectados en las superficies compatibles. - Dashboard Apps: puente versionado de contexto de solo lectura; escrituras en REST/MCP. Casos de uso - Sincronizar contactos y conversaciones con un CRM externo. - Disparar automatizaciones en tu sistema cuando algo cambia en la plataforma. Consejos, límites y buenas prácticas - Trata los tokens como secretos; nunca los expongas en el front-end. - Respeta los límites de tasa y maneja errores/reintentos. Solución de problemas - 401/403: verifica el token y los permisos. - El webhook no llega: revisa la URL, el estado del endpoint y la firma. Ver también - SDK, API REST y MCP de Dashboard Apps - API REST, tokens y webhooks - SDK de Custom Scripts - Referencia de API (Swagger / OpenAPI)

API REST, tokens y webhooks

Visión general La API REST permite leer y escribir datos de la plataforma (contactos, conversaciones, mensajes y más). La autenticación usa un token de acceso, y los webhooks entregan eventos a tu sistema en tiempo real. Requisitos previos - Un token de acceso válido. - Un endpoint HTTPS para recibir webhooks. Paso a paso 1. Genera un token de acceso en la configuración. 2. Incluye el token en el encabezado de autenticación de tus llamadas a la API. 3. Realiza solicitudes a los recursos de la API (ej.: listar contactos, crear conversación). 4. Configura un webhook indicando la URL y los eventos deseados. 5. Valida la firma/secreto del webhook antes de procesar el payload. Configuración y opciones - Alcance del token: limita el acceso a lo necesario. - Eventos del webhook: suscríbete solo a los eventos que usas. - Secreto de firma: se muestra una sola vez, justo después de crear el webhook. Cópialo y guárdalo de forma segura; las respuestas de listado y edición solo confirman que hay un secreto configurado y nunca lo revelan. Si se pierde, crea un webhook de reemplazo y retira el destino anterior. - Entrega duradera: cada entrega de webhook de cuenta se registra antes de entrar en la cola. Los errores de red y respuestas 5xx usan reintentos con backoff y siguen visibles en el historial. - Historial y reenvío: en Configuración → Integraciones → Webhooks, abre el historial del destino para buscar, filtrar y ordenar intentos. Un administrador puede reenviar una o varias filas; el resultado masivo mantiene separados los IDs procesados y fallidos. - Payload de Commerce: por defecto solo se envían identificadores canónicos. Activa Incluir datos comerciales en un destino únicamente cuando el receptor necesite comprador, producto/variante e ítems normalizados. El opt-in nunca agrega credenciales ni el payload bruto de la pasarela. - Idempotencia del receptor: usa el encabezado X-Chatwoot-Delivery como clave de idempotencia; un reenvío manual reutiliza el mismo identificador. Catálogo de eventos (grupos de módulos) Todos los eventos siguientes son suscripciones a nivel de cuenta (configuradas por cuenta, en la pantalla de Webhooks). Para que un módulo entregue sus eventos, la función del módulo debe estar habilitada en la cuenta — la suscripción se acepta aunque la función esté apagada, pero no se entrega nada hasta activarla. - Conversaciones, mensajes, contactos, bandeja y escritura — el ciclo de vida de la atención. - CRM (negocios) — creación, etapa, ganado/perdido, prioridad, valor, salud, lista de tareas, SLA y fechas de cierre. - Catálogo y Commerce — productos, variantes/stock y el ciclo de pago de Commerce. - Pedidos e ingresos — registro de pedido, estado, pagado, reembolsado, ingresos y afiliados. - Tareas, Calendario y reservas, Pagos y Follow-ups — el ciclo de vida de cada módulo. - Contratos y firma electrónica, Gestión de Ventas y Engagement/Lead Score. - Account Brain — riesgo, insights, ejecución de departamento y mejoras propuestas. - Distribución (Grupos de Lanzamiento) — inscripción, invitación, ingreso de miembros y finalización de unidades. - Growth Social y Ads — comentarios, leads de anuncio, estado de campaña y ventana del Clic-a-WhatsApp. - WhatsApp Hub — difusiones, eventos de participantes y bienvenidas/despedidas de grupo (Cloud y WazMeow). - Llamadas y respuestas de Flow de WhatsApp — ciclo de vida de llamadas y respuestas de WhatsApp Flows. - Gestión de Equipo — cambio de estado, pausas y turnos de los agentes. - FlowBuilder — ciclo de vida de las sesiones de flujo. - Enrutamiento Inteligente — asignación de agente. Los campos reales de cada payload están en Eventos por módulo. Casos de uso - Replicar conversaciones en un data warehouse. - Notificar a un sistema externo cuando una conversación se crea o se resuelve. Consejos, límites y buenas prácticas - Verifica siempre la firma del webhook antes de actuar. - Garantiza idempotencia con X-Chatwoot-Delivery, también en reintentos y reenvíos manuales. - Respeta los límites de tasa y usa backoff en errores 429/5xx. Solución de problemas - 401/403: token inválido o sin permiso. - Webhook duplicado: confirma que el receptor deduplica X-Chatwoot-Delivery. - Entrega fallida: abre el historial del destino y revisa su estado HTTP/error y el próximo intento. Después de corregir el receptor, selecciona la fila y confirma el reenvío. Ver también - SDK, API REST y MCP de Dashboard Apps - Visión general de API y Desarrolladores - Eventos por módulo - Referencia de API (Swagger / OpenAPI)

Canal API: el contrato estructurado de eventos

Visión general El canal API es una bandeja de entrada de primera clase. Cualquier módulo de la plataforma la alcanza de la misma forma en que alcanza WhatsApp o el widget web: crea un mensaje en una conversación. Ese mensaje luego se envía por POST — firmado — a la URL del webhook de tu bandeja de entrada. Como cada payload de mensaje lleva el content_type completo y los content_attributes, el contenido estructurado (botones interactivos, CTAs de pago, tarjetas de catálogo, eventos de calendario y reacciones) llega a tu integración de forma nativa — tú lo renderizas. Todo lo aquí descrito es aditivo y retrocompatible: las integraciones existentes siguen funcionando y pueden ignorar cualquier campo que no reconozcan. No hay nuevos campos obligatorios. Requisitos previos - Una bandeja de entrada API con una URL de webhook configurada. - El secreto de la bandeja de entrada para verificar la firma del webhook (y opcionalmente hmac_token para HMAC de entrada). - Un token de acceso para la API REST cuando envías datos de vuelta. Paso a paso 1. Crea una bandeja de entrada API y define su URL de webhook. 2. Recibe eventos en esa URL y verifica la firma con el secreto de la bandeja de entrada. 3. Lee content_type + content_attributes en cada payload de mensaje para renderizar contenido enriquecido. 4. Envía mensajes de entrada, acuses de recibo y reacciones de vuelta a través de la API REST. 5. (Opcional) Restringe qué eventos recibes con webhook_subscriptions. Tipos de contenido de salida (lo que el webhook entrega) Cada payload message_created / message_updated incluye content_type, content, content_attributes y attachments. Más allá del text plano, la bandeja de entrada API puede entregar: - input_select — opciones interactivas en content_attributes.items ([{title, value}]). Cuando un canal no puede renderizar opciones, la plataforma también agrega un menú numerado a content. - content_attributes.payment_interactive — una acción de pago: { body, buttons: [{ type: "cta_url", text, url } | { type: "cta_copy", text, code }] }. El cobro completo (importe, código PIX, boleto, enlaces) también llega como content_attributes.payment_charge en el mensaje resumen. - content_attributes.catalog_product — una tarjeta de producto: { mode: "single" | "list", products: [{ id, name, price, currency, image_url, ... }] }. - content_attributes.calendar_event — una confirmación de reserva o recordatorio: { id, title, starts_at, ends_at, location, meet_url, kind: "confirmation" | "reminder" } (horas en ISO-8601). - content_attributes.reactions — un array de { emoji, sender_jid }. El operador es me; un contacto se guarda bajo su propio identificador. Las reacciones viajan en el evento message_updated. - Plantillas — los metadatos de la plantilla enviada viajan en additional_attributes.template_params ({ name, language, category, processed_params }). - Multimedia, ubicación, contactos, stickers — entregados como attachments reales (además de content_attributes.media_kind para los stickers). Entrada (lo que envías de vuelta) - Mensaje entrante — POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages con message_type: "incoming". Acepta content, content_type, content_attributes y attachments, de modo que una respuesta interactiva es simétrica con el contrato de salida. - Acuses de recibo — PUT/PATCH .../messages/{id} (solo bandejas de entrada API) con status de sent / delivered / read / failed (y un external_error opcional). Esto cambia el estado del mensaje, que se retransmite vía message_updated. - Reacciones — POST .../messages/{id}/react con emoji (un emoji vacío la elimina). Pasa by=contact para registrar la reacción del contacto (por defecto se registra la del operador). No se contacta a ningún proveedor para una bandeja de entrada API — la reacción se persiste y se retransmite vía message_updated. Campañas Las campañas puntuales pueden dirigirse a una bandeja de entrada API. Cada contacto de la audiencia recibe una conversación real y un mensaje saliente, que viaja por tu webhook exactamente como cualquier otro mensaje de salida. Configuración y opciones - webhook_subscriptions — un array opcional en los additional_attributes del canal API (actualiza la bandeja vía API con channel[additional_attributes][webhook_subscriptions]). Cuando se define, solo esos eventos se entregan; cuando está ausente o vacío, se entregan todos los eventos (el valor por defecto). Los nombres de eventos deben ser eventos válidos de la plataforma (por ejemplo, message_created, message_updated, conversation_created, conversation_status_changed, conversation_typing_on). - hmac_mandatory — rechaza las solicitudes de entrada que no puedan verificarse por HMAC. Casos de uso - Conecta la bandeja de entrada con una aplicación personalizada que renderice CTAs de pago, tarjetas de catálogo y reservas de calendario. - Retransmite la reacción de un contacto desde tu propio cliente de vuelta al mensaje. - Refleja confirmaciones de reserva y recordatorios en el canal de registro del cliente. Consejos, límites y buenas prácticas - Verifica siempre la firma del webhook antes de actuar sobre un payload. - Deduplica por el id de entrega / evento; espera reintentos. - Prefiere content_attributes para el renderizado estructurado; content es el respaldo en texto plano. - Suscríbete solo a los eventos que uses para reducir el ruido. Solución de problemas - No llegan eventos: confirma que la URL del webhook está definida y, si configuraste webhook_subscriptions, que el evento que esperas está en la lista. - 422 en las suscripciones: la lista contiene un nombre de evento desconocido — elimínalo. - La reacción no se atribuye al contacto: pasa by=contact en la llamada de reacción. Ver también - API REST, tokens y webhooks - Eventos por módulo - Referencia de la API (Swagger / OpenAPI)

Referencia de API (Swagger / OpenAPI)

Visión general Conversa Labs publica una referencia completa de la API en formato OpenAPI 3.1, generada automáticamente a partir de las rutas reales del producto. Cubre todos los módulos — conversaciones, contactos, CRM, catálogo, pagos, agenda, tareas, follow-ups, ventas y gamificación, WhatsApp y mucho más — y se mantiene sincronizada con la API en cada build. Hay dos formas de ver la misma referencia: - ReDoc (lectura) — una documentación navegable, organizada por grupos y tags, ideal para entender el contrato de cada endpoint: https://app.conversalabs.com.br/swagger - Swagger-UI (interactiva) — la misma referencia con el botón "Try it out" para hacer llamadas reales a la API directamente desde el navegador: https://app.conversalabs.com.br/swagger/ui.html - Definición OpenAPI (JSON) — el archivo en bruto para importar en Postman, Insomnia o generar SDKs: https://app.conversalabs.com.br/swagger/swagger.json Requisitos previos - Un token de acceso válido (generado en tu perfil/cuenta). Consulta el artículo de API REST y tokens. - Un navegador moderno. Para probar llamadas, prefiere un token de un entorno de pruebas. Paso a paso 1. Abre la referencia en https://app.conversalabs.com.br/swagger (ReDoc) y navega por los grupos de módulos en la barra lateral. 2. Localiza el endpoint que necesitas (por método y ruta) y lee sus parámetros, cuerpo y respuestas. 3. Para probar, abre la referencia interactiva en https://app.conversalabs.com.br/swagger/ui.html. 4. Haz clic en Authorize e ingresa tu token en el encabezado api_access_token. 5. Elige un endpoint, haz clic en Try it out, completa los parámetros y haz clic en Execute. 6. Revisa la respuesta (estado, cuerpo) y reutiliza el ejemplo de solicitud (cURL) en tu integración. Configuración y opciones - Generación automática: la referencia se construye a partir de la introspección de las rutas reales de la aplicación, así que los nuevos endpoints aparecen automáticamente. - Autenticación: todos los endpoints autenticados usan el encabezado api_access_token. - Disponibilidad: en instalaciones self-hosted, la documentación la habilita el operador mediante una variable de entorno (ENABLE_API_DOCS). En la Conversa Labs alojada ya está disponible en las direcciones anteriores. Casos de uso - Descubrir rápidamente qué endpoints existen para un módulo (CRM, Pagos, Catálogo, etc.). - Probar una llamada con tu token antes de escribirla en el código. - Importar la definición OpenAPI en Postman/Insomnia o generar un SDK cliente. Consejos, límites y buenas prácticas - Trata el token como un secreto — no lo compartas ni lo expongas en el front-end. - Para pruebas, usa un token con el menor alcance posible y, preferiblemente, de un entorno de pruebas. - Respeta los límites de tasa y maneja los errores 429/5xx con backoff. Solución de problemas - La página no abre (404): la documentación puede estar deshabilitada en ese entorno — el operador la habilita con ENABLE_API_DOCS. - 401/403 al probar: el token es inválido o no tiene permiso; genera uno nuevo y revisa el alcance. - Un endpoint no aparece: puede requerir un módulo/recurso no habilitado en tu cuenta. Ver también - SDK, API REST y MCP de Dashboard Apps - API REST, tokens y webhooks - Visión general de API y Desarrolladores - Eventos por módulo

SDK de Custom Scripts

Visión general Los Custom Scripts permiten inyectar JavaScript/CSS en superficies específicas de la plataforma — el dashboard, el portal del Centro de Ayuda y el widget de chat. Son útiles para pequeñas personalizaciones de comportamiento y estilo sin cambiar el código base. Requisitos previos - Permiso de administrador para gestionar Custom Scripts. - Conocimientos de JavaScript/CSS. Paso a paso 1. Abre el módulo de Custom Scripts. 2. Crea un script y elige la superficie (dashboard, portal o widget). 3. Define el tipo (JS o CSS) y cuándo debe ejecutarse. 4. Usa el contexto ctx que provee el runtime para interactuar con la superficie de forma segura. 5. Implementa el teardown para limpiar lo que el script creó, cuando aplique. Configuración y opciones - Superficie: dashboard / portal / widget. - Tipo: JS o CSS. - Ejecución: reglas de cuándo se ejecuta el script. Casos de uso - Añadir un botón o aviso en una pantalla específica. - Ajustar estilos puntuales de una superficie. - Registrar eventos de uso para análisis interno. Consejos, límites y buenas prácticas - Escribe scripts idempotentes y con teardown para evitar duplicación. - Evita dependencias pesadas; prefiere código ligero. - Prueba en un entorno controlado antes de publicar. Solución de problemas - El script no se ejecuta: confirma la superficie y las reglas de ejecución. - Comportamiento duplicado: revisa el teardown y la idempotencia. Ver también - Visión general de API y Desarrolladores - Custom Scripts (Administración)

SDK, API REST y MCP de Dashboard Apps

Descripción general Los Dashboard Apps nativos tienen tres contratos separados: - El SDK V2 del navegador entrega contexto limitado por capacidades, eventos de solo lectura, comandos seguros e identidad firmada opcional para el backend propio de la app. - La API REST permite a administradores o roles personalizados con integration_manage crear, consultar, actualizar, reordenar y eliminar apps e instalaciones. - El servidor MCP expone el mismo contrato con cuatro herramientas opcionales en Canales e integraciones → Dashboard Apps. El SDK autentica solo una identidad breve de la app incrustada; no ofrece un proxy de API genérico. Las escrituras deben pasar por tu backend, autenticado en REST con un token de privilegio mínimo. Requisitos previos - dashboard_apps_native_surfaces habilitada en la cuenta. - Dashboard App HTTPS en un origen diferente del dashboard de Conversa Labs para V2. - Un administrador o rol personalizado con integration_manage y un api_access_token para gestión REST. - Para MCP, perfil cuyo usuario actuante tenga ese permiso y que incluya Dashboard Apps. - CSP frame-ancestors que permita el origen exacto de Conversa Labs, sin X-Frame-Options incompatible. Paso a paso 1. Conecta el SDK V2 en el navegador Importa el SDK desde la ruta estable y versionada de tu despliegue de Conversa Labs. Redirige al build actual con fingerprint y expone exportaciones con nombre del módulo JavaScript. import { connect } from '/dashboard-app-sdk/v2.js'; try { // El host inyecta parámetros cl_*; origen e instalación se descubren automáticamente. // Las opciones explícitas siguen disponibles para pruebas controladas. const client = await connect(); const stop = await client.subscribe( ['context.initialized', 'conversation.changed', 'theme.changed'], event => console.log(event.context_revision, event.data) ); await client.setHeight(520); document.querySelector('#documentacion').addEventListener('click', () => { client.openLink('https://app.ejemplo.com/docs'); }); // Después: await stop(); client.disconnect(); } catch (error) { console.error(error.code); } Usa las importaciones con nombre del módulo mostradas arriba. Son el contrato estable para aplicaciones nuevas. Si tu aplicación no puede consumir exportaciones con nombre, el mismo archivo también expone window.ConversaLabsDashboardAppSDK, con las mismas funciones. Llama a connect() apenas cargue la página, no detrás de autenticación ni de una ida a tu backend. El host inicia el handshake cuando el marco termina de cargar y reintenta hasta 10 segundos; una aplicación que empieza a escuchar después de esa ventana recibe handshake_timeout. Un import estático al inicio de un <script type="module"> es la forma soportada. Un import() dinámico funciona si se espera de inmediato — no dejes la carga del SDK para después de renderizar la pantalla. connect lee cl_dashboard_origin y cl_installation_id de la URL, valida el origen exacto, negocia protocolo 2.0 y resuelve tras el handshake. El cliente expone installationId, capabilities, connected, subscribe, unsubscribe, setHeight, openLink, getIdentityAssertion y disconnect. Los eventos incluyen contexto, conversación, estado/asignación/etiquetas, mensajes, contacto/usuario, idioma/tema/permisos e instalación. La conversación es omnicanal y funciona para correo, WhatsApp, SMS y otros inboxes; la barra lateral omite conversación y contacto. Programa según capabilities, campos opcionales y context_revision creciente; resincroniza datos antiguos. Identidad segura para n8n y otros backends No envíes identidad ni credenciales en la query string del iframe. En context.initialized, usa: - account.id y account.name para identificar la cuenta; - current_user.id, current_user.name, current_user.role y current_user.avatar_url para identificar a la persona que abrió la app; - installation.id, surface, sidebar_category y sidebar_icon en barra lateral para identificar instalación, lugar, categoría nativa e icono elegido; - en la superficie de conversación, conversation, contact, permissions y eventos de mensajes para el contexto operativo. El bridge nunca expone tokens de usuario/sesión/CSRF, REST, MCP ni credenciales del proveedor del canal. Cuando se conceden por instalación, current_user:email añade el correo del usuario actual; contact:email y contact:phone añaden datos del contacto en conversación. Sin la capacidad, el campo se omite del contexto y los eventos. Para que un backend propio o webhook n8n verifique identidad sin confiar en IDs del navegador, pide una aserción breve: const identity = await client.getIdentityAssertion(); await fetch('https://app.ejemplo.com/api/dashboard-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(identity), }); El backend envía assertion por POST a la introspection_url recibida, opcionalmente con expected_origin: "https://app.ejemplo.com". Una respuesta activa contiene claims de cuenta, usuario, instalación, superficie y capacidades. La aserción expira en dos minutos y cada introspección revalida feature, instalación, usuario activo, membresía, audiencia y origen. El verificador público rechaza aserciones mayores de 16 KiB antes de verificar la firma. No es un token REST/MCP y no debe almacenarse ni usarse como bearer. Datos y escrituras adicionales usan la credencial REST de privilegio mínimo o el perfil MCP restringido del backend. 2. Gestiona instalaciones por REST Todas las rutas pertenecen a la cuenta. Con la feature desactivada responde 404 resource_not_found; un miembro autenticado sin permiso de gestión recibe 403 forbidden en esas operaciones. # Lista instalaciones visibles; administradores también reciben audience. curl -sS "https://soporte.ejemplo.com/api/v1/accounts/1/dashboard_app_installations?surface=conversation" \ -H "api_access_token: API_TOKEN" # Crea una instalación. dashboard_app_id queda inmutable. curl -sS -X POST "https://soporte.ejemplo.com/api/v1/accounts/1/dashboard_app_installations" \ -H "api_access_token: API_TOKEN" -H "Content-Type: application/json" \ --data '{"dashboard_app_installation":{"dashboard_app_id":42,"surface":"conversation","compatibility_mode":"v2","enabled":true,"position":0,"capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"],"audience":{"type":"any","roles":["administrator"],"team_ids":[7],"user_ids":[]}}}' # Actualiza o reordena con el lock_version de la respuesta más reciente. curl -sS -X PATCH "https://soporte.ejemplo.com/api/v1/accounts/1/dashboard_app_installations/9" \ -H "api_access_token: API_TOKEN" -H "Content-Type: application/json" \ --data '{"dashboard_app_installation":{"sidebar_category":"applications","sidebar_icon":"rocket","position":1,"lock_version":3}}' # Elimina. curl -sS -X DELETE "https://soporte.ejemplo.com/api/v1/accounts/1/dashboard_app_installations/9" \ -H "api_access_token: API_TOKEN" La lista devuelve { "payload": [...], "meta": { "revision": N } }; crear, ver y actualizar devuelven { "payload": { ... } }; eliminar devuelve 204. La instalación incluye app id/título/URL, surface, compatibility_mode, enabled, visible operativo, position, sidebar_category y sidebar_icon solo en barra lateral, capabilities, audience solo para administradores, transport_security, warnings, lock_version y updated_at. POST /api/v1/accounts/:account_id/dashboard_app_installations/:id/identity_assertion es la llamada autenticada usada por getIdentityAssertion; aplica feature, instalación V2/dual activa, audiencia y capacidades. Las apps deben preferir el SDK. La validación server-to-server usa el endpoint público POST /dashboard-apps/v2/assertions/introspect descrito arriba. También puedes crear app e instalaciones iniciales atómicamente con installations en POST /dashboard_apps. Con la feature habilitada, omitir la propiedad crea la instalación por defecto conversation + legacy + all; un array vacío crea solo la app. Con la feature deshabilitada, enviar installations se rechaza y omitirla conserva la creación heredada. Cada app puede tener una instalación por superficie. 3. Usa las herramientas MCP de la cuenta Habilita Dashboard Apps en el perfil MCP. El módulo permanece en channels_integrations, conserva las herramientas existentes de definición de app y añade: | Herramienta | Efecto | Perfil de solo lectura | |---|---|---| | list_dashboard_app_installations | Lista instalaciones visibles al usuario actuante | Disponible | | create_dashboard_app_installation | Crea una instalación | Oculta | | update_dashboard_app_installation | Actualiza categoría, icono, posición, audiencia o bridge | Oculta | | delete_dashboard_app_installation | Elimina una instalación | Oculta | MCP usa el mismo ámbito, política, audiencia, feature y errores que REST. El detalle REST y el alias PUT no son herramientas separadas: list es la lectura canónica y PATCH la actualización/reordenación canónica. La emisión de identidad no es una herramienta MCP: pertenece a la sesión humana incrustada, mientras MCP ya posee su propio principal autenticado. Configuración y opciones - Superficies: conversation o sidebar. - Modos: legacy, v2 o dual. - Capacidades: núcleo obligatorio; conversación/contacto/mensajes solo para conversation; datos personales opcionales current_user:email, contact:email, contact:phone; identidad opcional identity:assertion. Omitirlas aplica el valor completo y útil de la superficie; un array vacío explícito se rechaza con invalid_capabilities. Elimina solo concesiones opcionales y conserva todas las capacidades obligatorias para la superficie seleccionada. - Audiencia: { "type": "all" } o { "type": "any", "roles": [...], "team_ids": [...], "user_ids": [...] }. Roles válidos: agent y administrator; any exige un selector no vacío y concede acceso si cualquiera coincide. - Categoría lateral: support, contacts_crm, applications, commercial, productivity, automation, growth o analytics_config; solo se acepta en sidebar y el valor predeterminado es productivity. El grupo applications queda justo debajo de Contactos y CRM y se omite vacío. - Icono lateral: panels_top_left, layout_dashboard, app_window, boxes, briefcase, bot, calendar_days, chart_no_axes_combined, circle_dollar_sign, clipboard_list, database, folder, globe_2, headphones, life_buoy, messages_square, package, rocket, shopping_bag, sparkles, workflow o wrench; solo se acepta en sidebar, con panels_top_left como valor predeterminado. - Posición: índice desde cero normalizado por superficie y, en barra lateral, por categoría. - Concurrencia: envía lock_version; 409 stale_installation exige recargar y reintentar. - Errores estables: invalid_audience, invalid_capabilities, invalid_sidebar_category, invalid_sidebar_icon, installation_already_exists, invalid_dashboard_app_url, dashboard_app_migration_required, unsafe_same_origin_v2 y resource_not_found. El error de migración exige un marco HTTP(S); query string y fragmento son válidos. - Límites SDK: 64 KiB por mensaje, 32 suscripciones, 30 comandos por 10 segundos y altura 160–2.000 px. - Los plazos del handshake son dos, independientes. El panel abre la ventana cuando el marco carga y reenvía la invitación hasta 10 segundos. El connect() del SDK tiene su propio límite de 10 segundos desde la llamada, ajustable con connect({ timeoutMs }). Subir el del SDK no ayuda: el panel deja de reintentar antes. - Ciclo de vida: el SDK emite eventos de ventana conversalabs.dashboard-apps:bridge.connected, :bridge.paused, :bridge.resumed y :context.resynced. Escúchalos para pausar trabajo cuando la pestaña pierde el foco y para resincronizar. El código disconnected significa que todo comando posterior será rechazado; reconecta en lugar de reintentar el comando. Códigos de error y lo primero que revisar | Código | Significa | Empieza por | |---|---|---| | handshake_timeout | El panel reintentó 10 s y la aplicación no respondió | ¿Llama a connect() al cargar? ¿El bundle cargado expone connect? | | invalid_origin | Origen configurado o del bridge inválido | URL HTTP(S) sin credenciales; en V2 el origen debe diferir del panel | | frame_blocked | El navegador rechazó la incrustación | frame-ancestors y X-Frame-Options en el servidor de la aplicación | | insecure_transport_blocked | Aplicación HTTP dentro de un panel HTTPS | Publica la aplicación por HTTPS | | unsupported_version | Aplicación y panel no comparten versión del bridge | Usa el SDK del mismo despliegue | | unsupported_command | Comando fuera de la allowlist | Usa solo los comandos anunciados | | invalid_payload | Mensaje fuera del contrato | Versión, secuencia, campos y tamaño | | invalid_sequence | Mensaje fuera de orden | No reimplementes el protocolo a mano; usa el SDK | | rate_limited | Más de 30 comandos en 10 s | Baja la frecuencia y agrupa suscripciones | | disconnected | El bridge se cerró | Reconecta; los comandos pendientes no vuelven | | user_denied | La persona rechazó la confirmación | Esperado en openLink; no insistas | | capability_denied | Capacidad no concedida | Actívala en la instalación; los datos de contacto solo existen en conversación | | identity_unavailable | No se pudo emitir la aserción | Feature, modo V2/dual, instalación activa y audiencia | Casos de uso - Mostrar contexto de conversación manteniendo cambios del CRM en un backend auditable. - Provisionar instalaciones desde un servicio administrativo interno. - Permitir que un perfil IA de solo lectura inventaríe apps sin escritura. - Usar MCP de escritura en un perfil administrador restringido para automatización controlada. Consejos, límites y buenas prácticas - Fija dashboardOrigin al origen HTTPS exacto. No uses *, no aceptes orígenes postMessage no confiables ni reimplementes el protocolo si existe el SDK. - Query string y fragmento estáticos se conservan. En V2/dual el host añade y sobrescribe solo cl_dashboard_origin, cl_installation_id, cl_account_id, cl_surface, cl_protocol y cl_locale; trata todo nombre cl_* como reservado. El host elimina los valores cl_* estáticos antes de escribir esos seis parámetros. Nunca pongas tokens, aserciones, secretos ni datos personales en la URL o bundle. - Mantén credenciales REST/MCP en el servidor, rótalas y separa perfiles de inventario y administración. - Autoriza audiencia en el servidor. Ocultar una pestaña no es autorización. - openLink siempre muestra una confirmación nativa del host. El enlace solo se abre después de que la persona pulse Abrir enlace; nunca se confía en un timestamp del iframe como prueba de gesto. - Maneja códigos de DashboardAppSDKError, desconexión, límites y resincronización. - insecure_http es una señal de migración, no aprobación para producción. Solución de problemas - handshake_timeout: el panel reenvió la invitación durante 10 segundos y la aplicación no respondió. Empieza por la aplicación, no por la red: ¿llama a connect() apenas carga la página? ¿El bundle que cargó expone connect? Solo después revisa el origen y el modo V2/dual. Un marco en blanco es otro problema — consulta frame_blocked. - El modo Dual oculta el fallo de V2: con Dual, la atención sigue por el lane heredado y la superficie aparece lista aunque el bridge V2 esté muerto. El diálogo Probar muestra el resultado de cada bridge por separado; para ver el error crudo, cambia la instalación a V2 temporalmente. - invalid_origin: usa una URL HTTP(S) sin credenciales incrustadas y mantén V2 en un origen distinto al del panel. - unsupported_version o unsupported_command: usa el SDK del mismo despliegue y capacidades anunciadas. - capability_denied: habilita la capacidad solicitada; correo/teléfono del contacto existe solo en la superficie de conversación. - identity_unavailable o introspección inactiva: pide una aserción nueva y verifica feature, modo V2/dual, instalación activa, audiencia, membresía y origen exacto. - rate_limited o invalid_payload: reduce frecuencia, tamaño y suscripciones. - REST/MCP devuelve 404: revisa cuenta, instalación y feature; la audiencia también puede ocultarla. - REST/MCP devuelve 403: el usuario autenticado o actuante no es administrador ni posee un rol personalizado con integration_manage. - 409 al actualizar: obtiene el estado actual y repite con su lock_version. - 422 al crear/actualizar: revisa error, URL, par app/superficie, categoría lateral, audiencia y origen V2. Ver también - Dashboard Apps: superficies nativas, audiencia y seguridad - API REST, tokens y webhooks - Referencia de API (Swagger / OpenAPI) - MCP nativo: conexiones, servidor y clientes

Eventos por módulo

Visión general Varios módulos de la plataforma emiten eventos cuando algo cambia — se crea una conversación, se confirma un pago, un negocio cambia de etapa, etc. Puedes reaccionar a estos eventos vía webhooks o mediante las reglas de automatización internas. Requisitos previos - Webhooks configurados (para consumo externo) o acceso a Automatización (para reacciones internas). Paso a paso 1. Identifica el evento del módulo que quieres consumir (ej.: conversación creada, pago pagado). 2. Para consumo externo: suscríbete al evento en el webhook y maneja el payload en tu endpoint. 3. Para reacciones internas: crea una regla de automatización con el disparador correspondiente. 4. Valida y procesa el payload de forma idempotente. Configuración y opciones - Webhooks: suscripción por bandeja/cuenta. - Automatización: disparadores por evento, con condiciones y acciones. - Payload: contiene el contexto del evento (ids y datos relevantes). Nuevos eventos por módulo (payloads reales) Los campos siguientes provienen de la fuente real de cada evento — no inventes el formato. Todos se entregan a webhooks de cuenta; las llamadas y respuestas de Flow también van al webhook del canal de API. La entrega de cada grupo requiere la función del módulo habilitada en la cuenta (la suscripción funciona aunque la función esté apagada, pero no se entrega nada). Gestión de Equipo — función: Gestión de Equipo - wfm_status_changed, wfm_break_started — el agente cambió de estado / entró en pausa. Campos: account_id, account_user_id, user_id, status_key, status_event_id, base_availability, family. - wfm_break_breached — la pausa superó el límite. Campos: los anteriores más expected_seconds y over_by_seconds. - wfm_break_ended — el agente salió de una pausa (cualquier vía: cambio manual, selector nativo o auto-offline). Campos: los del inicio de pausa más duration_seconds, within_limit y, si se excedió, over_by_seconds. - wfm_shift_started, wfm_shift_ended — la ventana del turno planificado del agente se abrió/cerró (evaluado en el servidor cada minuto). Campos: account_id, account_user_id, user_id, shift_id, schedule_id (cuando se genera desde una plantilla), date, starts_at, ends_at. Cada evento del ciclo se dispara exactamente una vez por turno. Difusiones del WhatsApp Hub — función: WhatsApp Hub - whatsapp_broadcast_started, whatsapp_broadcast_completed, whatsapp_broadcast_failed — la difusión cambió de estado. Campos (sin contenido de mensaje): account_id, inbox_id, broadcast_id, display_id, title, status, target_type, recipients_count. Funciona en bandejas Cloud y WazMeow (WhatsApp Web). Bienvenidas y despedidas de grupo de WhatsApp — función: WhatsApp Hub - whatsapp_group_member_welcomed, whatsapp_group_member_farewelled — se disparan solo cuando el mensaje de bienvenida/despedida se envió realmente (idempotente, una vez por participante por ventana de deduplicación). Campos: account_id, inbox_id, whatsapp_group_id, group_jid, participant_jid, participant_phone, trigger (welcome o farewell). Sin contenido de mensaje. Ads Manager — función: Growth Ads o Ads Manager - ads_campaign_status_changed — el estado efectivo de una campaña reflejada cambió. Campos: account_id, ad_account_id, campaign_id, remote_id, status, effective_status, previous_effective_status. - ctwa_conversation_started — una conversación por Clic-a-WhatsApp abrió la ventana gratuita de 72h. Campos: account_id, conversation_id, contact_id, inbox_id, window_id, expires_at. - ad_window_expiring — esa ventana está por expirar. Mismos campos. Llamadas y respuestas de Flow de WhatsApp — función: WhatsApp Inbox Suite - whatsapp_call_started, whatsapp_call_ended, whatsapp_call_recording_ready — el ciclo de vida de la llamada. Campos (los presentes varían según la etapa): provider_call_id, conversation_id, realtime, status, recording_url. Entregado a webhooks de cuenta y de canal de API. - whatsapp_flow_response_received — el cliente completó un WhatsApp Flow. Campos: el objeto flow_response (id, whatsapp_flow_id, screen, response, contact_id, conversation_id) y el objeto conversation. Entregado a webhooks de cuenta y de canal de API. Sesiones del FlowBuilder — función: Flow Builder - flow_session_started, flow_session_updated, flow_session_completed, flow_session_failed — la sesión del flujo se inició, se pausó, se completó o falló. Campos: id, flow_id, status, current_node_id, conversation_id, account_id. Casos de uso - Actualizar un sistema externo cuando se confirma un pago. - Disparar una cadencia de follow-up cuando un negocio cambia de etapa. Consejos, límites y buenas prácticas - Consulta siempre la fuente real del payload antes de mapear campos (no inventes el formato). - Garantiza idempotencia por identificador del evento. Solución de problemas - El evento no llega: confirma la suscripción y el estado del endpoint. - Campos inesperados: revisa el payload real recibido y ajusta el mapeo. Ver también - API REST, tokens y webhooks - Reglas de automatización - Canal API: el contrato estructurado de eventos

MCP nativo: Conexiones MCP, servidor de Maestro y cliente (Model Context Protocol)

Visión general El MCP (Model Context Protocol) es el estándar abierto que permite a asistentes de IA (Claude, IDEs, agentes) usar herramientas y datos de sistemas externos de forma segura. Conversa Labs incorpora MCP nativo, y todo se opera desde pantallas — sin escribir integración. Hay tres superficies: - Conexiones MCP de la cuenta (perfiles de acceso) — en lugar de una única configuración de la cuenta, creas N perfiles con nombre. La conexión de Bearer estático de cada perfil tiene su selección de módulos, modo solo lectura, usuario de ejecución (miembro de la cuenta) y URL + secreto bearer propios. Esa conexión estática opera como el usuario de ejecución y solo puede restringir lo que ya puede hacer, nunca ampliarlo. Cuando la instalación habilita OAuth nativo, el mismo perfil también tiene una URL OAuth separada: las herramientas siguen limitadas por el perfil, pero cada llamada opera como el miembro que aprobó el consentimiento OAuth — nunca como el usuario estático del perfil. - Servidor MCP de Maestro — expone los departamentos de Maestro como herramientas ask_<departamento> a clientes externos, con un token por cuenta. El cliente nunca gana más autonomía de la que el departamento ya tiene configurada. - Robot como cliente MCP — cada robot puede consumir servidores MCP externos (Linear, Notion, Stripe, GitHub, un ERP interno) como herramientas adicionales, con las mismas reglas de aprobación (HITL), presupuesto de herramientas y auditoría que el resto. La conexión estática de la cuenta y el servidor de Maestro usan la cabecera estándar Authorization: Bearer <credencial>. Los ejemplos siguientes configuran ese camino estático: en la cuenta, la credencial es el secreto del perfil; en Maestro, el token de Maestro. Son ejemplos de configuración, no una prueba de que todos los productos o versiones estén validados en esta instalación. El OAuth nativo de cuenta es un recurso separado y condicional, con discovery, PKCE y consentimiento en el navegador; no dirijas un cliente OAuth a la URL estática ni supongas compatibilidad sin probarla. Identidad visual del conector Durante la inicialización MCP con el protocolo 2025-11-25, el servidor envía el nombre y el título de la instalación, descripción, sitio web e iconos de marca (uno principal y variantes clara/oscura). Las pantallas de inicio de sesión y consentimiento OAuth usan la misma identidad; si la imagen configurada no carga, muestran las iniciales de la instalación. Estos metadatos solo se publican cuando existe un origen canónico público y seguro en HTTPS. Sin él, el servidor omite URL e iconos en vez de exponer una dirección interna o no confiable. El cliente decide si muestra estos campos y cómo hacerlo. Los clientes que negocian una versión MCP más antigua todavía reciben el nombre técnico del servidor, pero ese protocolo no puede transportar iconos. En el Conector personalizado de Claude, usa el nombre introducido en su configuración: la interfaz puede seguir mostrando ese nombre hasta que use los metadatos del servidor. La apariencia no modifica scopes, consentimiento ni credenciales. Los endpoints de Cuenta, Plataforma y Super Admin construyen esta instantánea segura en cada inicialización MCP. Después de cambiar White Label o el emisor canónico, la misma instantánea versionada se encola para el endpoint directo de Maestro; la siguiente solicitud autenticada usa la instantánea válida persistida más reciente. Una indisponibilidad temporal de Maestro nunca revierte la marca guardada: el reconciliador programado vuelve a intentarlo. Si el proveedor ya creó un conector, desconéctalo y agrega el servidor de nuevo para forzar otro initialize; esto no rota tokens ni cambia permisos. La URL del icono debe ser un recurso de primera parte de ese mismo origen canónico, público, HTTPS y accesible sin inicio de sesión; un CDN externo u otro host no se publica como metadato de marca MCP. Un cliente de terceros puede conservar el icono en caché u optar por no renderizar metadatos de icono MCP; el servidor no puede sustituir ese comportamiento. Requisitos previos - La función MCP habilitada para la cuenta. Sin la flag, la página Ajustes → MCP simplemente no aparece en el menú (y el interruptor global de la instalación también debe estar activado). - Perfil de administrador de la cuenta para gestionar las Conexiones MCP (la página y la creación/edición de perfiles son solo para administradores). - Para la conexión de la cuenta: ningún token personal. Cada perfil (Conexión MCP) genera su propio secreto bearer al crear/rotar — esa es la credencial del cliente. El usuario de ejecución del perfil debe ser miembro de la cuenta. Los tokens de robot (AgentBot) y el token personal de API no son la credencial de la conexión de la cuenta. - Para la conexión opcional de OAuth nativo de la cuenta: el responsable de la instalación debe habilitar OAuth nativo de MCP, aplicar las migraciones de base de datos de OAuth MCP de esta versión y configurar un emisor público HTTPS válido, además de la función MCP de la cuenta y el interruptor global. Una flag no sustituye la migración del esquema ni prueba el flujo. La URL OAuth es distinta de la conexión estática; el secreto estático del perfil nunca la autentica. Quien aprueba el consentimiento en el navegador debe ser miembro activo de la cuenta. - El host del emisor debe resolver y enrutar a través de la pasarela pública hacia esta misma instalación. Debe servir los endpoints MCP OAuth y los documentos de Metadatos de Recurso Protegido y discovery del servidor de autorización; una dirección HTTPS sintácticamente válida que enruta a otro lugar no basta. - Antes de adoptar OAuth nativo en un cliente de terceros, prueba discovery, PKCE y consentimiento en un entorno controlado. Un endpoint basado en estándares no prueba que un producto, aplicación de escritorio o superficie de IA alojada soporte el flujo requerido. - Para el servidor de Maestro: Maestro aprovisionado en la cuenta. Sin eso, la tarjeta de Maestro se sustituye por un aviso. - Para conectar un servidor MCP externo por OAuth: el robot ya guardado y el navegador habilitado para abrir ventanas emergentes (la pantalla de consentimiento del proveedor se abre en una ventana). Paso a paso 1. Abrir la página MCP Ve a Ajustes → MCP. La pantalla muestra la tarjeta Conexiones MCP de la cuenta (los perfiles de acceso) y la tarjeta Servidor MCP de Maestro. 2. Crear una Conexión MCP (perfil de acceso) En la tarjeta Conexiones MCP de la cuenta, pulsa Nuevo perfil. Cada perfil es una conexión independiente: 1. Dale un nombre al perfil (por ejemplo claude-code-soporte o bi-solo-lectura) — ayuda a identificar qué cliente usa cada conexión. 2. Elige el usuario de ejecución — un miembro de la cuenta. El perfil se ejecuta como ese usuario: la lista de herramientas efectiva es la intersección de tu selección con el techo del Super Admin y con los permisos de ese usuario. Es decir, un perfil solo restringe — nunca concede más de lo que el usuario ya tiene. Solo pertenecen a este servidor las rutas ancladas en /api/v{N}/accounts/{account}: las rutas personales de perfil, MFA, sesiones y notificaciones quedan fuera de la conexión de la cuenta, incluso cuando el usuario también pertenece a otras cuentas. 3. Elige los módulos que se exponen. Es el mismo selector de siempre: toda la plataforma (más de 100 módulos), organizada en áreas plegables: Conversaciones y atención, Contactos y CRM, Catálogo y ventas, Pagos, Tareas y agenda, WhatsApp, Canales e integraciones, Automatización e IA, Growth y ventas, Informes, Equipo y administración y Contenido. Usa la búsqueda para encontrar un módulo por su nombre o descripción, y el Seleccionar todo de cada área para activarla entera de una vez. Cada fila indica qué hace el módulo y cuántas herramientas agrega (el precio de la casilla); el resumen bajo la búsqueda suma la selección actual y avisa si supera el tope de herramientas — que sigue valiendo por perfil: Algunos ejemplos (la lista completa está en pantalla, por área): | Ejemplo de módulo | Qué expone | |---|---| | Conversaciones | leer, responder, cambiar estado, asignar, aplicar etiquetas (activado por defecto) | | Contactos | buscar, crear y actualizar contactos (activado por defecto) | | Informes | métricas y análisis (solo lectura) | | Tareas | módulo nativo de tareas | | Ítems de CRM | negocios y pipeline | | Centro de Ayuda | artículos de la base de conocimiento | | Catálogo | productos | | Follow-up | cadencias de follow-up | | Biblioteca de Medios | archivos de medios | Los toolsets activos de fábrica llevan el distintivo default. Si el Super Admin no liberó un toolset en el techo global, la fila aparece deshabilitada y con el distintivo bloqueado por el super admin — no puedes marcarla. Encima de la lista hay atajos de punto de partida: Esencial, Atención, Comercial y Todo. Solo suman módulos a la selección actual — no se quita nada, y ningún módulo desaparece de la lista porque un atajo no lo mencione. Usa uno para empezar y ajusta a mano; los módulos bloqueados por el techo siguen fuera, como siempre. 4. Modo solo lectura: marca la casilla para que el perfil exponga solo herramientas que leen datos (sin crear, actualizar ni borrar). 5. Compatibilidad con la investigación profunda de ChatGPT (opcional): el conector de investigación profunda de ChatGPT exige, por nombre, dos herramientas llamadas search y fetch, y rechaza un servidor que no las tenga. Marca la casilla solo en los perfiles que use ese conector. Las dos herramientas solo describen lo que el perfil ya expone — no otorgan ningún acceso adicional —, pero ocupan sitio en la lista de los demás clientes. Déjalo desactivado para Claude, Claude Code y clientes genéricos. 6. Guarda el perfil. En ese momento el secreto bearer se muestra en texto plano exactamente una vez (formato mcp_...) — cópialo al momento. Solo se guardan el hash y los cuatro últimos caracteres; la plataforma no vuelve a mostrar el secreto. 7. Copia la URL de la conexión. Su forma es https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO, donde ID_PUBLICO es un identificador no secreto (un slug en la URL) — quien autentica es el secreto bearer, no la URL. Esta es la URL de Bearer estático. Si la instalación habilitó OAuth nativo de MCP, el mismo perfil tiene otro recurso exacto: https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/oauth/c/ID_PUBLICO. No sustituyas mcp/c por esta ruta en un cliente estático existente y no pegues allí el secreto del perfil. El perfil sigue seleccionando las herramientas, pero las llamadas OAuth se ejecutan como el miembro que aprobó el consentimiento. Después, cada perfil tiene, en la tarjeta, los botones Editar (cambia nombre, usuario de ejecución, módulos y modo solo lectura), Rotar token (genera un secreto nuevo e invalida el anterior al instante) y Eliminar. Desactivar o eliminar el perfil — o que el usuario de ejecución deje de ser miembro de la cuenta — hace que la conexión deje de responder (401/404). 3. Configurar el servidor MCP de Maestro 1. En la tarjeta Servidor MCP de Maestro, mira el estado: Token configurado o Aún sin token. 2. Pulsa Generar token (o Rotar token si ya existe uno). 3. El token en texto plano se muestra exactamente una vez — cópialo al momento. No se vuelve a mostrar. Rotar invalida el token anterior de inmediato. 4. Copia la URL del endpoint de Maestro (termina en /mcp). 5. Un cliente externo con esa URL + token ve una herramienta ask_<departamento> por cada departamento activo de la cuenta. Si Maestro no está configurado en la cuenta, la tarjeta se sustituye por un aviso — aprovisiona Maestro antes. 4. Conectar un cliente MCP con Bearer estático Esta sección configura solo la conexión de Bearer estático: usa Streamable HTTP, la URL estática del perfil del paso 2 (o la URL de Maestro del paso 3) y la credencial en la cabecera Authorization: Bearer .... En la cuenta es el secreto del perfil (el mcp_... revelado al crear o rotar); en Maestro es el token de Maestro. Los formatos de configuración de clientes cambian fuera de esta documentación; valida la versión exacta en un entorno controlado. Ningún snippet siguiente configura OAuth nativo. Claude Code — desde la terminal: claude mcp add --transport http helpdesk \ https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO \ --header "Authorization: Bearer SECRETO_DEL_PERFIL" O en el .mcp.json del proyecto: { "mcpServers": { "helpdesk": { "type": "http", "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" } } } } Cursor — en ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto): { "mcpServers": { "helpdesk": { "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" } } } } VS Code (modo agente) — en .vscode/mcp.json: { "servers": { "helpdesk": { "type": "http", "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" } } } } MCP Inspector — para depurar la conexión y ver la lista cruda de herramientas: npx @modelcontextprotocol/inspector En el panel: Transport Type = Streamable HTTP, URL = la URL de la conexión y, en Authentication, indica el Bearer Token — el secreto del perfil para la conexión de la cuenta, o el token de Maestro para el servidor de Maestro (o una cabecera Authorization con el valor Bearer <credencial>). Pulsa Connect y luego List Tools. Windsurf — misma idea: servidor remoto con la URL de la conexión y headers con Authorization: Bearer SECRETO_DEL_PERFIL (o el token de Maestro). En todos, el cliente ejecuta initialize, luego tools/list (lista las herramientas expuestas) y finalmente tools/call para ejecutar una. Si el cliente muestra menos herramientas de las esperadas, es el tope de exposición: usa search_tools para encontrar cualquier otra herramienta (devuelve su esquema) y call_tool para ejecutarla. Nada queda inalcanzable — solo fuera de la lista. 4a. Conectar el recurso OAuth nativo de la cuenta (condicional) Esta es una ruta de conexión separada, disponible solo cuando OAuth nativo de MCP está habilitado en la instalación y la función/perfil MCP de la cuenta están disponibles. No convierte la conexión de Bearer estático y no es una alternativa para un secreto de perfil perdido. 1. Configura el cliente con la URL exacta del recurso OAuth: https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/oauth/c/ID_PUBLICO. 2. Comienza por los Metadatos de Recurso Protegido de ese recurso, no por una URL de host adivinada: https://TU-DOMINIO/.well-known/oauth-protected-resource/mcp/oauth/accounts/ID_DE_CUENTA/connections/ID_PUBLICO. Solo anuncian el servidor de autorización canónico mientras el recurso esté disponible. 3. Descubre el servidor de autorización en https://TU-DOMINIO/.well-known/oauth-authorization-server/oauth/mcp (o usa el emisor anunciado por los metadatos). El servidor usa Authorization Code público, PKCE S256 obligatorio, vínculo al recurso exacto y ningún secreto de cliente. Los metadatos de discovery declaran authorization_response_iss_parameter_supported: valida el emisor canónico devuelto en el parámetro iss en los callbacks de éxito y de error redireccionable. El handoff firmado del navegador acepta como máximo 1.024 bytes combinados entre sus valores de autorización persistidos (incluidos client_id, redirect_uri, resource y state). Mantén state corto y opaco; no intentes ampliar el flujo con URL o estados demasiado grandes. 4. Un cliente público puede usar Client ID Metadata público verificado (CIMD). Registro Dinámico de Clientes (DCR) es condicional y está apagado por defecto: solo aparece en discovery después de que un Super Admin habilite Dynamic Client Registration en MCP Settings. Si está apagado, discovery omite registration_endpoint y el registro devuelve 404 — eso no es una falla de OAuth. Cuando está activado, el operador revisa el cliente en MCP OAuth clients y puede desactivarlo; la desactivación confirmada, con razón y reautenticación, es irreversible y revoca la familia de consentimiento/tokens. DCR sigue siendo un camino de prueba gobernado, no una promesa de compatibilidad de proveedor. Nunca envíes a este flujo un secreto de perfil, token personal de API, credencial de Super Admin o secreto de cliente. 5. En el navegador, cuando una sesión activa del panel de la cuenta o de la Consola de Super Admin pertenece a un miembro de la cuenta destino, el servidor la valida y reutiliza: vas directamente a revisar el consentimiento sin escribir de nuevo la contraseña. La aprobación sigue siendo obligatoria. Una identidad Super Admin entra en este flujo solo cuando también tiene membresía en la cuenta, y el grant/token permanece limitado a la cuenta, al perfil y a los scopes — no hereda autoridad global. Si la sesión falta, caducó, no es válida o pertenece a otra cuenta, aparece el formulario manual y exige una identidad de miembro válida. mcp:read es el alcance de lectura; las herramientas de escritura también requieren mcp:write y un perfil que no sea de solo lectura. offline_access solicita explícitamente un refresh token rotativo. 6. En Ajustes → Perfil → Conexiones MCP, un miembro revisa y revoca sus propias conexiones aprobadas. Un administrador de cuenta revisa todos los grants de la cuenta y debe elegir una razón cerrada cuando revoca mediante el flujo administrativo. La revocación invalida la familia de credenciales conectada. 4b. Verificar el recurso público antes de conectar un cliente OAuth Antes de abrir Claude.ai, Claude Code u otro cliente remoto, un operador puede verificar el contrato público sin proporcionar ninguna credencial: ruby scripts/mcp_oauth_preflight.rb \ --base-url https://TU-DOMINIO \ --account-id ID_DE_CUENTA \ --profile-public-id ID_PUBLICO Para la autoridad separada de Super Admin, usa: ruby scripts/mcp_oauth_preflight.rb \ --base-url https://TU-DOMINIO \ --super-admin El verificador acepta solo un origen HTTPS público con nombre DNS (rechaza IP literal y host interno), no sigue redirecciones y comprueba los Metadatos de Recurso Protegido exactos, emisor y audiencia, discovery, Client ID Metadata (CIMD), PKCE S256, el parámetro de respuesta iss, scopes y el desafío 401 de un tools/list JSON-RPC sin Bearer. Cuando discovery anuncie DCR, también comprueba el endpoint exacto; la ausencia explícita porque el gate está apagado es un estado válido. Continúa con la prueba controlada solo cuando termine con RESULT: PASS. Si falla, corrige la publicación antes de conectar cualquier cliente. Ese resultado confirma la publicación del servidor; no prueba que un proveedor externo sea compatible. No registra un cliente, no abre consentimiento, no intercambia/revoca un token y no cambia un perfil, grant o credencial. La instancia remota puede agregar su telemetría de auditoría normal sin secretos para discovery y el desafío 401; es observabilidad, no un cliente OAuth creado por el verificador. Claude.ai — Conector personalizado Después de que un operador habilite OAuth MCP y Ajustes → MCP muestre la Dirección de conexión OAuth del perfil, usa el área de conectores de Claude correspondiente a tu plan: Usa este recorrido como prueba controlada de la versión de Claude disponible para tu organización. No ofrezcas la conexión a otras personas hasta registrar discovery, consentimiento, tools/list, una lectura y una revocación correcta. El conector remoto de Claude alcanza el servidor desde la infraestructura en la nube de Claude, incluso cuando usas Claude Desktop. Por tanto el emisor debe ser HTTPS público y alcanzable fuera de una VPN/red privada; que solo sea accesible desde tu navegador no basta. Los conectores personalizados remotos están disponibles en Claude, Cowork y Claude Desktop en los planes Free, Pro, Max, Team y Enterprise; Free está limitado a un conector personalizado. Consulta también la guía actual de conectores remotos de Claude. 1. En Team/Enterprise, Owner o Primary Owner va a Organization settings → Connectors → Add → Custom → Web y registra la URL MCP remota. Luego cada miembro va a Customize → Connectors y pulsa Connect. En Free/Pro/Max, usa Customize → Connectors → + → Add custom connector en tu propia cuenta (Free permite un conector). 2. Dale un nombre claro, por ejemplo Conversa Labs — Soporte, y pega la Dirección de conexión OAuth en URL MCP remota. No uses la URL Bearer estática. 3. Advanced settings es opcional. En este servidor de cliente público, nunca rellenes Client Secret ni uses token Bearer, secreto del perfil o credencial de Super Admin en ningún campo. Si la versión de Claude necesita DCR, habilítalo explícitamente antes mediante Super Admin; de lo contrario debe usar CIMD o un cliente ya provisionado. 4. Añade el conector, inicia sesión como miembro activo de la cuenta y lee/aprueba el consentimiento. Claude actúa como esa persona, limitado por el perfil, sus propios roles y los scopes. El callback lo controla el cliente y es información de registro, no una URL que debas sustituir manualmente en el recurso MCP. Registra la versión de Claude y el callback recibido en la prueba; no pongas tokens, códigos ni parámetros de callback en la evidencia. Para desconectar, revoca el grant en Ajustes → Perfil → Conexiones MCP (o, como administrador, desde la misma vista de cuenta). No rotes un token bearer estático: es otro tipo de conexión y no desconecta Claude OAuth. No marques un producto de terceros como compatible solo porque ofrece MCP u OAuth. Valida producto, versión, redirección y resultado del consentimiento de punta a punta antes de permitirlo a usuarios. Matriz de conectores externos — prueba controlada Todas las filas siguientes están sin validar en esta instalación. La matriz explica cómo preparar un intento seguro; no declara soporte del proveedor. Empieza siempre con mcp:read, initialize, tools/list y una lectura sobre datos de prueba. Prueba una escritura solo después de autorización explícita. | Cliente | Requisitos externos | Pasos de prueba controlada | Revocación | Estado | |---|---|---|---|---| | Claude.ai — Conector personalizado | Plan Claude con conectores personalizados (Free: uno); en Team/Enterprise Owner/Primary Owner lo registra antes; emisor HTTPS público alcanzable desde la nube de Claude y preflight aprobado | Usa la URL OAuth exacta, mantén Advanced settings opcional/sin secreto y completa navegador/PKCE/consentimiento | Revoca en Ajustes → Perfil → Conexiones MCP y confirma que la llamada siguiente falla | ⏳ sin validar | | Claude Desktop | Claude Desktop actualizado y cuenta con conectores personalizados; el servidor también debe ser alcanzable desde la nube de Claude, no solo desde la máquina local | Configura solo la URL OAuth exacta y registra versión, sistema y callback/error seguro | Revoca el mismo grant y prueba otra llamada | ⏳ sin validar | | Codex | La organización/producto es elegible para MCP remoto y su método actual de conexión está disponible | Añade solo la URL OAuth exacta en el flujo actual del producto; nunca uses un secreto Bearer como secreto de cliente | Revoca el grant y confirma la denegación posterior | ⏳ sin validar | | ChatGPT / GPT Platform | Plan/workspace elegible, administrador o Developer Mode cuando aplique y autorización explícita para la prueba | Usa el flujo de connector/app realmente disponible, la URL OAuth exacta y consentimiento en navegador | Revoca el grant y confirma la denegación posterior | ⏳ sin validar | El recurso OAuth de Super Admin es otro plano de autoridad y usa otra URL; nunca sustituyas la URL de Cuenta anterior por /super_admin/mcp/oauth. Sigue el artículo de Operador y realiza una prueba separada. Registra versión, plan/entitlement, resultado de discovery, consentimiento, tools/list, lectura, evento de auditoría, revocación y la llamada denegada — sin copiar tokens, códigos, verificadores ni URLs con parámetros de autorización. Claude Code: la autorización local usa un callback loopback con puerto efímero. La política de redirect RFC 8252 restringida para ese callback ya tiene matcher y prueba HTTP locales; una URL fija localhost/127.0.0.1 no representa por sí sola el puerto real. Esto no prueba compatibilidad: el E2E externo sigue bloqueado hasta disponer de emisor HTTPS público, Inspector y evidencia del cliente real. 5. Dar servidores MCP externos a un robot (el robot como cliente) 1. Ve a Ajustes → Robots, abre el robot y busca la sección Servidores MCP. 2. Pulsa Añadir servidor y completa: - Nombre técnico — letras minúsculas, números y _, empezando por letra (2 a 33 caracteres), por ejemplo github. Prefija las herramientas de ese servidor. - URL del servidor MCP (la que publica el proveedor). - Transporte: Streamable HTTP (recomendado) o SSE (legado). - Timeout en segundos. 3. Autenticación: elige el tipo — ninguna, bearer, header, query, basic u OAuth. En los tipos con secreto, indica el nombre del secreto — nunca el valor. El valor queda en la bóveda de secretos y nunca se envía al modelo. El tipo OAuth no tiene campo de secreto: la credencial se obtiene en el paso 6. 4. Cabeceras adicionales (opcional): pares clave/valor, solo si el servidor las exige. 5. Marca Exigir aprobación (HITL) para que toda llamada a las herramientas de ese servidor pase por aprobación humana. 6. Pulsa Descubrir: la plataforma se conecta al servidor en ese momento y lista sus herramientas antes de guardar. Los servidores grandes (Linear, Notion) devuelven decenas de herramientas con descripciones largas — usa la búsqueda y Seleccionar todo / Limpiar para curar sin recorrer toda la lista; el contador indica cuántas marcaste. Puedes seleccionar un subconjunto (allowlist) — si no seleccionas ninguna, quedan disponibles todas las herramientas de ese servidor. 7. Guarda el robot. Las herramientas se descubren y almacenan al guardar; el turno del agente nunca hace descubrimiento de red. Para que el descubrimiento resuelva secretos ya almacenados, guarda el robot primero y luego pulsa Descubrir. 6. Conectar un servidor externo por OAuth (botón Conectar) Algunos servidores (Notion, por ejemplo) solo aceptan OAuth — no existe clave estática. En esos casos: 1. En el servidor MCP del robot, elige Autenticación → OAuth. Los campos de secreto desaparecen — no hay nada que rellenar. 2. Guarda el robot (la conexión se guarda por robot + nombre del servidor). 3. Pulsa Conectar. Se abre inmediatamente una ventana de autorización neutra; mantenla abierta. Cuando la plataforma recibe la dirección del proveedor, esa ventana navega a la pantalla de consentimiento en un contexto aislado: el proveedor no puede acceder a la pestaña del Studio. Inicia sesión y autoriza. 4. La ventana se cierra sola al terminar y el estado pasa a Conectado (con la validez y el alcance, cuando el proveedor los informa). Si permanece abierta después de la confirmación del proveedor, ciérrala para que el Studio pueda consultar el estado. Si el navegador bloquea la ventana, permite popups para este sitio e inténtalo de nuevo. 5. Pulsa Descubrir y sigue normalmente: las herramientas del servidor ya valen para el robot. 6. Desconectar olvida las credenciales de ese par robot + servidor. Para cambiar de cuenta en el proveedor: desconecta y conecta de nuevo. Las credenciales OAuth quedan cifradas en Maestro, atadas al par robot + servidor. Nunca se guardan en Conversa Labs, nunca aparecen en pantallas ni registros y nunca se envían al modelo. Configuración y opciones - Perfiles (Conexiones MCP) de la cuenta: cada perfil tiene nombre, usuario de ejecución estático, selección de toolsets, modo solo lectura, URL estática (con public_id) y secreto bearer propio (revelado una sola vez, rotable). La selección estática efectiva es siempre selección ∩ techo del Super Admin ∩ permisos del usuario de ejecución. - OAuth nativo de cuenta (condicional): el recurso OAuth es la URL separada /mcp/oauth/c/ID_PUBLICO. Usa la superficie de herramientas del perfil, pero al miembro que consintió, no al usuario estático. Sus grants son visibles/revocables en Ajustes → Perfil → Conexiones MCP; los grants existentes siguen visibles para revocación si el servidor se deshabilita después. - Modo solo lectura: por perfil, expone solo herramientas de lectura. - Compatibilidad con la investigación profunda de ChatGPT: por perfil, añade las dos herramientas search y fetch que ese conector exige por nombre. Solo describen lo que el perfil ya expone. Cuestan dos plazas del límite de herramientas (el servidor reserva cuatro en vez de dos cuando está activo), así que déjalo desactivado para Claude y clientes genéricos. - Límite de herramientas: hay un tope por servidor (512), aplicado por perfil — recorta la lista, no el acceso. Las meta-herramientas search_tools (descubre, con el esquema) y call_tool (ejecuta por nombre) alcanzan todo lo que el perfil habilitó, respetando el modo solo lectura, los permisos del usuario de ejecución y el techo del Super Admin. - Token de Maestro: uno por cuenta, revelado una sola vez, rotable en cualquier momento. - Servidores externos por robot: nombre técnico, URL, transporte, timeout, autenticación, cabeceras extra, aprobación (HITL) y allowlist de herramientas. - Tipos de autenticación (servidor externo): | Tipo | Cómo funciona | Cuándo usarlo | |---|---|---| | ninguna | no se envía nada | servidores realmente públicos (raro) | | bearer | envía Authorization: Bearer <secreto> | el caso más común — el secreto guarda la clave de API | | header | envía una cabecera con el nombre que elijas y el valor del secreto | el proveedor usa un esquema propio | | query | envía el secreto como parámetro en la URL | proveedores heredados | | basic | usuario + contraseña (dos secretos) | servidores internos | | OAuth | botón Conectar → consentimiento en el proveedor | el proveedor solo acepta OAuth (Notion) | - Presupuesto de herramientas: las herramientas de cada servidor externo cuentan en el presupuesto de herramientas del robot — demasiados servidores revientan el límite. - Protección SSRF: las direcciones privadas/internas están bloqueadas al añadir un servidor externo. Casos de uso - Operar la bandeja de entrada desde Claude Code o un IDE: listar conversaciones, responder, resolver. - Un perfil por cliente: cada IDE, script o socio recibe su propia conexión, con alcance mínimo y — en los clientes de lectura — el modo solo lectura activado. - Traer los informes de la cuenta a un asistente mediante un perfil solo lectura, ejecutado por un usuario de perfil restringido. - Revocar un único cliente: rota (o elimina) el perfil de ese cliente — los demás perfiles siguen funcionando. - Dar a un robot acceso a un sistema interno (ERP, base de conocimiento) mediante un servidor MCP externo, con aprobación humana en las acciones sensibles. - Dejar que el robot abra incidencias en Linear o lea una base en Notion durante la atención. - Dejar que el equipo de datos pregunte ask_riesgo / ask_financiero y reciba los hallazgos del departamento sin abrir el panel. Consejos, límites y buenas prácticas - Qué autenticación elegir en cada servidor externo popular (la mayoría responde 401 con un desafío OAuth, pero también acepta una clave de API normal en Authorization: Bearer — dejarlo en ninguna es la causa número 1 de que falle el descubrimiento): | Servidor MCP externo | Autenticación a elegir | |---|---| | Linear | bearer + secreto con la clave de API | | Stripe | bearer + secreto con la clave restringida | | GitHub | bearer + secreto con un token personal (PAT) | | Atlassian (Jira/Confluence) | bearer + secreto con el token de API | | Sentry | header con nombre Authorization y un secreto cuyo valor sea Sentry-Bearer TU_TOKEN | | Notion | OAuth (botón Conectar) — no acepta clave estática | | Servidor interno propio | lo que exija el servidor | - Secreto estático frente a consentimiento OAuth: el secreto estático del perfil lleva los permisos del usuario de ejecución estático — nunca más de lo que ya tiene. Un grant OAuth nativo opera como el miembro que consintió y queda vinculado al recurso OAuth exacto. Trata ambos como credenciales y no los intercambies entre las dos URLs. - Un perfil por cliente: así das alcance mínimo a cada uno y puedes rotar/eliminar un perfil para cortar solo a ese cliente, sin tocar a los demás. - Solo lectura primero: empieza cada perfil con el modo solo lectura activado y habilita la escritura por toolset a medida que confías en el cliente. - Menos es más: expón solo los toolsets que el cliente realmente usa — listas enormes de herramientas empeoran las decisiones del modelo. - Copia el secreto del perfil al momento: no se vuelve a mostrar. ¿Lo perdiste? Rota el token del perfil (el anterior se invalida al instante) y actualiza el cliente que lo usaba. - Secretos por referencia: en servidores MCP externos, nunca pegues el valor del secreto en el campo — indica la clave del secreto. - Copia el token de Maestro al momento: no se vuelve a mostrar. ¿Lo perdiste? Rota (y actualiza los clientes que usaban el anterior). - Aprobación (HITL): para servidores externos que escriben en sistemas críticos, marca Exigir aprobación. Solución de problemas - El cliente muestra menos herramientas que los módulos que activé en el perfil: es el tope de exposición del servidor. Las demás siguen siendo accesibles: pide al cliente que use search_tools (encuentra la herramienta y devuelve su esquema) y call_tool (la ejecuta por nombre). Para verlas en la lista, desmarca módulos o pide al operador que suba el tope. - La tarjeta de Maestro muestra una dirección interna (aviso ámbar): la instalación no declaró la dirección pública de Maestro. Un cliente en la misma máquina conecta; un IDE fuera de la red, no. El operador debe definir MAESTRO_PUBLIC_BASE_URL con la dirección pública de Maestro (y reiniciar la aplicación). - El cliente conecta por la dirección pública de Maestro y recibe "Invalid Host header" (o un 421): Maestro solo acepta el Host que la instalación declaró. Es el mismo MAESTRO_PUBLIC_BASE_URL — una vez definido, el host público se acepta (la protección contra DNS rebinding sigue activa). - Un conector aún muestra un icono antiguo o genérico: confirma que el origen canónico público HTTPS y la URL del icono cargan sin autenticación, guarda White Label y vuelve a conectar el proveedor para que ejecute initialize otra vez. El servidor conserva la última marca válida mientras Maestro reintenta tras una indisponibilidad temporal; el proveedor aún puede mantener caché o decidir no mostrar sus metadatos de icono. - La página MCP no aparece en el menú: la función MCP está apagada para la cuenta (pídeselo al operador) o tu usuario no es administrador. - 404 en el endpoint de la conexión: la función está apagada para la cuenta, el interruptor global de la instalación está desactivado, o el ID_PUBLICO de la URL no existe (perfil eliminado o desactivado). - 401 en la conexión de la cuenta: el secreto del perfil es incorrecto o fue rotado (el anterior se invalida al instante), el perfil fue eliminado/desactivado, o el usuario de ejecución dejó de ser miembro de la cuenta. Usa el secreto revelado al crear/rotar el perfil — un token personal de API y un token de robot no son la credencial de esta conexión. - Un cliente estático intenta iniciar sesión por OAuth: la URL estática de la cuenta termina en /mcp/c/ID_PUBLICO y acepta solo el secreto del perfil en Authorization: Bearer ...; no anuncia un servidor OAuth. Mantén ese cliente en la configuración de Bearer estático. - El recurso OAuth o discovery devuelve 404: OAuth nativo está deliberadamente dark-shipped. Revisa la habilitación de OAuth nativo, la función/perfil MCP de la cuenta y el emisor público; luego empieza de nuevo por los Metadatos de Recurso Protegido exactos. No sustituyas por un secreto estático ni token de otro plano. - La URL OAuth devuelve 401: falta el bearer OAuth, caducó, fue revocado o pertenece a otro recurso/plano de autoridad. Lee WWW-Authenticate: apunta a los Metadatos de Recurso Protegido exactos (e incluye invalid_token solo cuando se rechazó un Bearer enviado). Empieza de nuevo desde ese metadato; nunca pegues el secreto estático del perfil en esta URL. - La URL OAuth devuelve 403: el bearer es válido, pero la llamada pidió una herramienta de escritura sin el scope mcp:write. Pide ese scope en el consentimiento y confirma que el perfil no sea de solo lectura; mcp:write tampoco expone herramientas fuera del perfil. - La URL OAuth devuelve 413: la solicitud o respuesta JSON-RPC supera 1 MiB. Reduce la carga o usa paginación. Una solicitud grande se rechaza antes de ejecutarse; una respuesta grande se mide solo tras terminar la operación, así que no repitas una escritura a ciegas: revisa primero el recurso o la auditoría. - Un cliente OAuth todavía no completa el consentimiento: registra cliente y versión, URI de redirección, resultado de discovery y código de error seguro en una prueba controlada. No evites PKCE, vínculo al recurso o consentimiento en navegador; la compatibilidad solo existe tras una prueba de punta a punta. - Toolset en gris con el distintivo “bloqueado”: el Super Admin no liberó ese toolset en el techo global. Solo él puede liberarlo. - Perdí el secreto del perfil: genera otro con Rotar token en el perfil — el anterior se invalida al instante. - Perdí el token de Maestro: genera otro con Rotar token en la tarjeta de Maestro — el anterior se invalida al instante. - El descubrimiento (“Descubrir”) falla con 401: casi siempre la autenticación sigue en ninguna. Elige bearer y apunta el secreto a la clave de API del proveedor (Sentry usa header; Notion usa OAuth). - El descubrimiento falla por otro motivo: revisa la URL, el transporte (Streamable HTTP o SSE) y las credenciales; guarda el robot antes si la autenticación usa un secreto almacenado; las direcciones privadas/internas son rechazadas por la protección SSRF. - El botón Conectar no abre nada: el navegador bloqueó la ventana emergente — habilita los pop-ups para el dominio y vuelve a pulsar. - Conectado, pero la herramienta falla al cabo de un tiempo: la autorización del proveedor caducó — Desconecta y Conecta otra vez. - Una herramienta externa falla en ejecución: el error vuelve como texto al agente (que se autocorrige) y nunca tumba el turno. - ask_<departamento> responde “disabled”: el departamento está desactivado para la cuenta — actívalo en la pantalla del Cerebro (Account Brain). Ver también - SDK, API REST y MCP de Dashboard Apps - Referencia de la API (Swagger/OpenAPI) - Tokens REST, webhooks y autenticación - Bots y el canal de API

API y MCP de mensajes programados

Visión general La API de mensajes programados expone el mismo módulo usado por el dashboard. Siempre opera dentro de una cuenta y sobre una conversación existente. Las herramientas MCP se generan desde este contrato OpenAPI y aplican la misma autorización y validación. Requisitos previos - La función Mensajes programados habilitada en la cuenta. - Un token de usuario con acceso a la cuenta, Inbox y conversación. - Una política completa configurada en la cuenta. - Para crear, una clave X-Idempotency-Key estable de 1 a 128 caracteres. Paso a paso 1. Consulta GET /api/v1/accounts/{account_id}/message_scheduling/settings y verifica la política efectiva. 2. Envía la definición a POST .../message_schedules/preview. La vista previa no persiste ni envía. 3. Corrige todos los blockers y crea con POST .../message_schedules más X-Idempotency-Key. 4. Guarda id y lock_version. Repetir la misma clave y contenido devuelve la programación existente; contenido diferente devuelve 409. 5. Lista ocurrencias con GET .../message_schedules/{id}/occurrences. 6. En cambios y acciones, envía el lock_version actual y el scope exigido. Configuración y opciones - Tipos: one_time, sequence, recurring_single y recurring_sequence. - Alcances: this_occurrence, this_and_future y all_future. - send_now exige elegir si consume la ocurrencia o crea una copia inmediata. - reconcile exige un resultado observado: sent, failed o canceled. - Las acciones de programación usan all_future; resume también informa la acción publicada. - El destino, remitente efectivo, capabilities y draft normalizado son autoridad del servidor. En MCP, busca las herramientas en Message Schedules. Los nombres derivan del operationId; los argumentos y respuestas coinciden con Swagger. Casos de uso - Un CRM externo programa un retorno idempotente tras actualizar una oportunidad. - Un operador de IA usa MCP para consultar bloqueos y pausar una secuencia con confirmación humana. - Un proceso de reconciliación registra un resultado incierto sin duplicar el envío. Consejos, límites y buenas prácticas - Nunca reutilices una clave idempotente para una definición distinta. - Ante 409, vuelve a leer el recurso; no supongas ni incrementes el lock local. - No envíes campaign_id, audiencia, segmento ni listas de contactos. El contrato usa una conversación. - Usa la vista previa antes de crear y trata la validación al vencimiento como segunda autoridad. - No reintentes automáticamente needs_attention; verifica primero el efecto en el proveedor. - Consulta el OpenAPI publicado para schemas y ejemplos completos, incluidos drafts multipartes. Solución de problemas - 400 invalid_idempotency_key: corrige formato o longitud del header. - 401/403: revisa token, función, rol, Inbox y acceso a la conversación. - 409 stale_lock_version: recarga la programación u ocurrencia y reaplica la intención. - 422 preview_blocked: revisa cada código y corrige política, canal, remitente o contenido. - No aparece la herramienta MCP: confirma que el servidor publica el Swagger actual y actualiza la sesión/catálogo MCP. Ver también - Crear y administrar mensajes programados - Referencia de API (Swagger/OpenAPI) - Servidor y cliente MCP

Bots de atención y el canal de API

Visión general Conversa Labs ofrece dos puntos de extensión complementarios para desarrolladores: - Canal de API: un inbox programable. En lugar de un canal listo (WhatsApp, correo, etc.), creas una bandeja de entrada de tipo API y conectas tu propia aplicación. Los mensajes de entrada llegan por la API REST y las respuestas de los agentes se entregan en tu webhook_url. - Agent bot: un bot vía webhook (bot_type: webhook). Se asigna a un inbox (de cualquier canal) y recibe los eventos de conversación/mensaje en su outgoing_url. El bot procesa el evento y puede responder llamando de vuelta a la API con su token de acceso. Cuándo usar cada uno: - Usa el canal de API cuando necesites un canal a medida que la plataforma no ofrece de forma nativa. - Usa un agent bot cuando quieras automatizar respuestas (clasificación, respuestas automáticas, IA) antes o junto con la atención humana, en cualquier inbox. Ambos se pueden combinar: un inbox de API que además tiene un agent bot asignado. Requisitos previos - Permiso de administrador en la cuenta (crear inboxes y agent bots está restringido a admins). - Un endpoint HTTPS accesible para recibir webhooks (el webhook_url del canal y/o el outgoing_url del bot). - Un token de acceso válido para autenticar las llamadas a la API REST. Paso a paso 1. Crea un inbox de tipo API: ve a Configuración → Bandejas de entrada → Agregar → API. Indica un nombre y, opcionalmente, el webhook_url. Tras crearlo, anota el identifier generado para el canal. 2. Envía un mensaje de entrada: crea/abre una conversación en ese inbox y publica el mensaje del cliente vía API (POST .../conversations/:id/messages), autenticando con el token de acceso. 3. Configura el webhook_url del canal para recibir los mensajes de salida: cuando un agente responde en la conversación, el payload se entrega en tu endpoint. 4. (Opcional) Crea un agent bot: en Configuración → Agentes de IA/Agent bots, indica nombre, descripción y el outgoing_url (bot_type = webhook). Luego asigna el bot al inbox para que empiece a recibir los eventos de esa bandeja de entrada. Configuración y opciones - Token de acceso del bot: lo usa el bot para llamar de vuelta a la API (crear respuestas, reaccionar, actualizar estado). Se puede regenerar con reset_access_token. - Secreto del bot: se usa para firmar/verificar el payload del webhook enviado al outgoing_url. Se puede regenerar con reset_secret. - Verificación HMAC del canal (hmac_token, hmac_mandatory): valida la identidad del contacto. Con hmac_mandatory activo, los contactos solo se aceptan con un hash de identificación válido, calculado a partir del hmac_token. - Actualización de estado de mensaje: permitida solo en inboxes de API (por ejemplo, marcar entregado/leído o registrar un error de envío). - Payload del bot (webhook_data): identifica al bot en el evento con { id, name, type: "agent_bot" }. Casos de uso - Canal a medida: conectar una aplicación propia (una app interna, un marketplace, un canal propietario) como un inbox vía API. - Respuestas automáticas: un agent bot que hace la clasificación inicial, responde preguntas frecuentes y solo entonces pasa la conversación a un agente humano. Consejos, límites y buenas prácticas - Verifica siempre la firma HMAC del webhook (canal y/o secreto del bot) antes de procesar el payload. - Garantiza la idempotencia: al crear mensajes de entrada, usa un source_id único para deduplicar reentregas. - Define un punto de traspaso claro del bot al humano (por ejemplo, asignar la conversación a un agente/equipo y dejar de responder con el bot). - Trata tokens y secretos como credenciales: nunca los expongas en el front-end. Solución de problemas - 401/403: token de acceso inválido, expirado o sin permiso. - El bot no recibe eventos: confirma que el outgoing_url es correcto y accesible, y que el bot está asignado al inbox. - HMAC inválido: el hash de identificación no coincide con el hmac_token; vuelve a calcular la firma y revisa el orden/codificación de los campos. Ver también - API REST, tokens y webhooks - Eventos por módulo - Canal API: el contrato estructurado de eventos

API de Plataforma (aprovisionamiento multicuenta)

Visión general La API de Plataforma opera por encima de las cuentas: permite crear y gestionar cuentas, usuarios, vinculos usuario-cuenta y agent bots de forma programatica. Todo vive bajo un Platform App — una aplicacion de plataforma que el operador crea y que recibe su propio token. Diferencia con la API REST de la cuenta: - La API REST trabaja dentro de una sola cuenta (contactos, conversaciones, mensajes) y usa el token de un usuario/agente de esa cuenta. - La API de Plataforma trabaja entre cuentas (aprovisionamiento y ciclo de vida) y usa el token del Platform App. Sus endpoints viven bajo el prefijo /platform/api/v1. Un Platform App solo ve y modifica los objetos de su lista de permisibles (las cuentas, usuarios y bots que creo o que se le asociaron). Requisitos previos - Un Platform App creado por el operador (Super Admin -> Platform Apps). - El token de acceso de ese Platform App (generado junto con el app). - El token debe circular solo en el backend del operador — nunca en el front-end. Paso a paso 1. El operador crea un Platform App en Super Admin -> Platform Apps. Al guardar, la plataforma genera un token de acceso vinculado al app. 2. Autentica cada llamada incluyendo la cabecera api_access_token con el token del Platform App. Si el token no pertenece a un Platform App, la respuesta es 401 Invalid access_token. 3. Crea una cuenta: POST /platform/api/v1/accounts api_access_token: <token-de-plataforma> Content-Type: application/json { "name": "Cliente XPTO", "locale": "es", "support_email": "soporte@cliente.com" } La cuenta creada se agrega automaticamente a los permisibles del app. 4. Crea un usuario: POST /platform/api/v1/users { "name": "Maria", "email": "maria@cliente.com", "password": "<contrasena-fuerte>" } El usuario tambien entra en los permisibles del app. Si ya existe un usuario con ese correo, la plataforma reutiliza el usuario existente. 5. Vincula usuario y cuenta (account_user) con un rol: POST /platform/api/v1/accounts/<account_id>/account_users { "user_id": <user_id>, "role": "administrator" } Usa administrator o agent en el campo role. 6. Aprovisiona agent bots: POST /platform/api/v1/agent_bots { "name": "Bot de Ventas", "account_id": <account_id>, "outgoing_url": "https://mi-bot/webhook" } Endpoints complementarios: GET/PATCH/DELETE /platform/api/v1/accounts/:id, GET :id y DELETE :id de usuarios, GET .../account_users (listar), DELETE .../account_users (quitar vinculo), GET :id/login (genera un enlace de acceso SSO para el usuario) y POST :id/token. Configuracion y opciones - Objetos permisibles: cada Platform App mantiene una lista de cuentas, usuarios y agent bots que puede gestionar. Los objetos que el app crea entran en esa lista automaticamente. - Alcance del token: el token del Platform App solo actua sobre los permisibles del app — no llega a cuentas/usuarios de otros apps ni a los datos internos de una cuenta (para eso, usa la API REST de la cuenta). - Parametros de cuenta: name, locale, domain, support_email, status, ademas de features, limits y custom_attributes. - Parametros de usuario: name, display_name, email, password y custom_attributes. Casos de uso - Onboarding multicliente / reventa: crear una cuenta por cliente y poblar usuarios en masa. - Aprovisionamiento estilo SSO: crear el usuario y generar el enlace de acceso (GET :id/login) para llevar al usuario directo al panel sin contrasena manual. - Ciclo de vida automatizado: crear, actualizar y desactivar cuentas y vinculos desde tu propio sistema (por ejemplo, al completar o cancelar una suscripcion). Consejos, limites y buenas practicas - Manten el token del Platform App solo en el backend del operador. Tiene poder de aprovisionamiento — nunca lo expongas en el front-end ni en apps cliente. - Trabaja con permisos restringidos: el app solo debe tocar los objetos que el mismo creo. - La eliminacion de cuentas y usuarios es asincrona (encolada) — una respuesta 200 indica que la eliminacion fue agendada, no completada en el mismo instante. - Maneja la idempotencia: crear un usuario con un correo ya existente reutiliza el registro; crear el mismo vinculo cuenta-usuario no lo duplica. Solucion de problemas - 401 Invalid access_token: el token no pertenece a un Platform App (o falta/es incorrecto en la cabecera api_access_token). - 401 Non permissible resource: el objeto (cuenta/usuario/bot) no esta en la lista de permisibles del app — estas intentando cambiar algo que el app no gestiona. - 404: el id indicado no existe. Ver tambien - API REST, tokens y webhooks - Referencia de API (Swagger / OpenAPI) - Vision general de API & Desarrolladores