Base de conocimiento de GetMyBot

MCP: interfaz programática

Cómo conectar un asistente de IA a GetMyBot para consultar ajustes y realizar tareas por encargo. Acceso, herramientas y referencia de MCP.

En esta página

MCP (Model Context Protocol) permite conectar un asistente de IA a GetMyBot. Por ejemplo, puedes pedirle: «Muestra mis bots y encuentra la reacción a /start». El asistente obtiene herramientas para consultar ajustes, crear reacciones o revisar estadísticas. Cada operación usa los permisos de tu token.

Para conectarlo, necesitas la dirección /mcp y un token personal. Si ya usas la API REST, puedes utilizar el mismo token. En MCP, una operación se llama herramienta; un documento que se puede consultar es un recurso; y una instrucción preparada para el asistente es un prompt.

Dirección y autorización

MCP está disponible en /mcp mediante POST y el transporte Streamable HTTP. Envía Authorization: Bearer <TOKEN_PERSONAL>. Sustituye el marcador por el token completo, incluido el prefijo mbp_…. Un PAT sirve tanto para REST como para MCP.

El token pertenece a una cuenta: list_bots muestra sus bots, y get_balance, get_transactions y connect_bot actúan en esa cuenta. Consulta La cuenta del token. Cada herramienta necesita los permisos (scopes) de la operación REST correspondiente. * permite el conjunto público de operaciones, pero no concede derechos adicionales al propietario del token.

Si el token se emitió para una cuenta ajena, las herramientas de la cuenta comprueban además los derechos de cuenta de su propietario. connect_bot requiere bots.create; las herramientas de facturación requieren billing.read o billing.write. El scope * no sustituye esos derechos. Si faltan, la respuesta será permission denied: missing cabinet right si la persona no es miembro de esa cuenta, o permission denied: missing cabinet right: <derecho> si carece de un derecho concreto. El propietario concede estos derechos en Acceso a toda la cuenta; MCP no permite administrar esos accesos.

Conectar Claude Code o Cursor

Abre Cuenta → Tokens personales y crea un token. Justo después de crearlo, la página muestra una configuración lista para copiar y un comando claude mcp add con el token insertado. Solo se muestran una vez, igual que el propio token.

Necesitas un token personal (mbp_…). Los tokens de API del proyecto (mb_live_…) sirven solo para la API REST de ese proyecto. Con uno de ellos, /mcp responderá 401 e indicará qué tipo de token necesitas.

Si escribes la configuración manualmente, usa la dirección de tu instalación, por ejemplo https://getmybot.dev/mcp, y sustituye <TOKEN_PERSONAL> por el token completo, incluido mbp_:

{
  "mcpServers": {
    "mybot": {
      "url": "https://getmybot.dev/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN_PERSONAL>"
      }
    }
  }
}

En Claude Code, guarda este bloque en el archivo .mcp.json del proyecto o añade el servidor con:

claude mcp add --transport http mybot https://getmybot.dev/mcp --header "Authorization: Bearer <TOKEN_PERSONAL>"

En Cursor, añade el mismo bloque en Settings → MCP → Add server. El cliente obtendrá automáticamente las herramientas, los recursos y los prompts. Si recibes 401, comprueba que después de Bearer hayas puesto un token personal completo, no un token del proyecto.

Herramientas por ámbito

Estas son las herramientas y los permisos necesarios. Su disponibilidad depende de la versión del servidor; consulta tools/list para ver la lista actual.

Bots (bots)

  • list_bots: bots:read
  • get_bot: bots:read
  • validate_bot_token: bots:write
  • connect_bot: bots:write
  • update_bot: bots:write
  • delete_bot: bots:write
  • sync_bot: bots:write
  • change_bot_token: bots:write
  • transfer_bot: bots:write
  • get_bot_settings: settings:read
  • update_bot_settings: settings:write; incluye test_user_ids, usuarios de prueba sin cargos
  • get_widget_email_readiness: settings:read. Envía bot_id para comprobar la configuración de respuestas del widget por correo. senderConfigured indica si se encontró un remitente; transportStatus puede ser configured, not_configured o unknown. Es un estado de configuración y no confirma la entrega.
  • get_widget_settings: settings:read
  • update_widget_settings: settings:write

En las versiones que los incluyan en tools/list, el propietario puede usar reveal_widget_identity_secret o rotate_widget_identity_secret con bots:write, bot_id y channel_id. Para rotar, añade confirm_breaking_rotation: true: la clave anterior deja de funcionar de inmediato, así que actualiza tu servidor. El secreto se devuelve en texto claro al cliente MCP y puede quedar en su historial; protégelo como una contraseña.

get_widget_settings devuelve el diseño, botón de apertura, ventana del chat, saludo, formulario previo, horario, comportamiento, sitios permitidos (origins), widgetKey y revisión revision. Para guardar, pasa esa revisión como expected_revision a update_widget_settings. Si alguien cambió los ajustes, la actualización se rechazará. No uses update_bot_settings en su lugar: escribir widget_experience por esa vía no aplica las mismas comprobaciones de estructura, propiedad del avatar y revisión.

Canales y plantillas de WhatsApp (bots)

MCP permite gestionar Telegram, WhatsApp, VK y el widget web. La lectura requiere bots:read y los cambios bots:write; no hay un permiso separado para canales.

  • list_channels: bots:read; canales del bot con platform (tg/wa/vk/web), external_id, nombre, estado y callback_url.
  • connect_channel: bots:write; conecta WhatsApp, VK o el widget web. Para platform: "web" no se necesitan credenciales, pero sí una lista origins no vacía.
  • delete_channel: bots:write; desconecta el canal.
  • list_wa_templates: bots:read; plantillas de WhatsApp con nombre, idioma, estado, categoría y cuerpo.
  • sync_wa_templates: bots:write; actualiza el catálogo desde Meta.
  • create_wa_template: bots:write; crea una plantilla y la envía a revisión de Meta.
  • update_wa_template: bots:write; modifica una plantilla con estado APPROVED, REJECTED o PAUSED.
  • delete_wa_template: bots:write; elimina una plantilla.

Los canales de Telegram se conectan con connect_bot. connect_channel sirve para wa, vk y web. Las categorías de plantillas son MARKETING, UTILITY y AUTHENTICATION. create_wa_template envía inmediatamente el borrador a Meta, pero la revisión es asíncrona. Consulta el estado con list_wa_templates y, si hace falta, actualiza el catálogo con sync_wa_templates.

La respuesta de connect_channel para platform: "web" es {"widget_key": "…"} en vez de {"id": …}. Repetir la conexión del mismo bot devuelve la misma clave y no crea un segundo widget. Para cambiar la apariencia o el comportamiento del widget, usa get_widget_settings y update_widget_settings.

MCP aún no permite subir archivos de cabecera para plantillas, como imágenes, vídeos o documentos. Hazlo en el panel web o por REST con POST /api/bots/{botID}/channels/{channelID}/templates/media.

Reacciones (reactions)

  • list_reactions: reactions:read
  • get_reaction: reactions:read
  • create_reaction: reactions:write
  • update_reaction: reactions:write
  • delete_reaction: reactions:write
  • import_reactions: reactions:write
  • test_formula: reactions:write; prueba una fórmula avanzada con un texto de ejemplo. Campos: bot_id, formula y sample; en REST este último se llama sample_text. El contexto está vacío: no se sustituyen ctx ni los parámetros; el texto de ejemplo se puede usar como {text} o {answer}.
  • reorder_reaction: reactions:write
  • get_reaction_links: reactions:read
  • list_reaction_folders: reactions:read
  • create_reaction_folder: reactions:write
  • update_reaction_folder: reactions:write
  • delete_reaction_folder: reactions:write
  • add_reaction_to_folder: reactions:write
  • remove_reaction_from_folder: reactions:write
  • add_reactions_to_folder: reactions:write

import_reactions crea reacciones, pero omite los archivos multimedia: el contexto MCP no dispone de la comprobación premium ni de un receptor de archivos de Telegram. Si el paquete SamBot incluye imágenes, vídeos o documentos, usa la importación REST completa, POST /api/bots/{botID}/reactions/import.

Difusiones (broadcasts)

  • start_broadcast: broadcasts:write; admite paid y un segmento por etiquetas opcionales.
  • get_broadcast: broadcasts:write; en las difusiones iniciadas desde una reacción con start_broadcast, el informe incluye blocked: bloqueos atribuidos a la difusión durante las 24 horas posteriores a la entrega.
  • pause_broadcast: broadcasts:write
  • resume_broadcast: broadcasts:write
  • cancel_broadcast: broadcasts:write

Ajustes de envío de email

Disponibilidad del envío. Las campañas y los correos automáticos requieren procesadores de entrega configurados en tu región. Conectar tu propio SMTP no garantiza por sí solo la disponibilidad del envío. Este SMTP también puede servir para copiar respuestas no leídas del widget si se cumplen los demás requisitos. Consulta la disponibilidad con soporte.

Cada proyecto puede elegir GetMyBot o su propio SMTP; la disponibilidad de campañas y correos automáticos depende de sus respectivos procesadores de entrega. El buzón de soporte y el correo entrante se configuran por separado. Consulta Email desde tu dominio.

  • get_email_smtp (settings:read): envía bot_id. La respuesta incluye mode y, para SMTP propio, los ajustes y version; nunca devuelve la contraseña.

  • put_email_smtp (settings:write): envía bot_id, host, port, security (starttls o tls), username, envelope_from y password. Al crear, omite expected_version; al modificar, indica la versión de get_email_smtp. Puedes omitir la contraseña solo si no cambian servidor, puerto, cifrado ni usuario. Se comprueban conexión y autenticación sin enviar correo.

  • delete_email_smtp (settings:write): envía bot_id y el expected_version actual para elegir el modo GetMyBot. El envío en este modo requiere un servidor de plataforma configurado en la región. Cambiar de modo reinicia la verificación de dominios.

get_email_smtp también devuelve delivery_workers con los estados journey y newsletter: configured, not_configured o unknown. Describen la configuración del servidor que responde, no confirman el estado de la cola ni la entrega. El campo independiente delivery_workers.newsletter_gate indica el estado general de admisión de las campañas de correo masivo: open, paused o unknown si no se puede comprobar. Con paused no se toman nuevos trabajos ni destinatarios, aunque los envíos ya iniciados pueden terminar. Esta pausa no detiene otros envíos de correo.

Para cambiar el SMTP debes ser propietario o tener derechos de reacciones y administración de soporte, además de un plan con email y las comprobaciones de seguridad aplicables. Si la versión ha cambiado, consulta los ajustes antes de reintentar.

Si están disponibles en tools/list, delete_email_domain recibe bot_id, domain_id, confirm: true; delete_email_inbound_route recibe bot_id, route_id, confirm: true; y delete_email_mailbox recibe bot_id, expected_version, confirm: true. Requieren settings:write; eliminar el buzón también exige administración de soporte. Obtén su versión con get_email_mailbox. No se puede borrar un dominio utilizado por campañas.

Validación de contenido

validate_content_for_channel (content:read) comprueba una versión guardada del contenido para un canal sin enviarla. Indica bot_id, document_id, version, la expected_revision actual y platform. Para comprobar un destinatario concreto, envía juntos recipient_id y channel_id; añade identity_id si es necesario. Usa list_content_test_recipients para consultar los destinatarios verificados disponibles.

El resultado contiene snapshot, errors y warnings. Si la revisión ya no coincide, consulta el contenido actual y vuelve a intentarlo. Se requieren permisos del proyecto y del constructor, además de las comprobaciones de seguridad aplicables. Consulta tools/list para comprobar la disponibilidad.

Ventanas emergentes

list_popups y get_popup requieren popups:read; create_popup_draft, update_popup_draft, set_popup_enabled y delete_popup requieren popups:write. La disponibilidad de estas operaciones y variantes A/B depende de la versión del servidor; consulta tools/list después de actualizarlo.

Para crear un borrador A/B nuevo y desactivado, envía ab_test: true y entre dos y cinco variantes a create_popup_draft. Antes de activarlo por primera vez puedes cambiar las variantes con update_popup_draft; al enviar variants, incluye la lista completa deseada y conserva los ID existentes. Activa la ventana con set_popup_enabled y enabled: true: las variantes quedan fijadas cuando las comprobaciones de activación se completan. Las variantes ya fijadas siguen sin poder modificarse aunque se desactive la ventana. Para eliminar una ventana, obtén updated_at con get_popup y pásalo como expected_updated_at junto con confirm: true a delete_popup. Una ventana activa deja de mostrarse inmediatamente; se conservan los eventos históricos y el registro del experimento.

Flujos automáticos

archive_campaign archiva un flujo que no está en estado running y delete_campaign lo elimina junto con su historial. clone_campaign_version copia la versión elegida en un nuevo borrador del mismo flujo y reemplaza el borrador actual. Las tres operaciones requieren confirm: true; guarda antes los cambios que necesites.

Gestiona las audiencias guardadas con list_broadcast_audiences, create_broadcast_audience y delete_broadcast_audience (para eliminar se requiere confirm: true). list_reaction_broadcast_recipients lista los destinatarios por páginas y list_reaction_broadcasts muestra el historial de envíos de la reacción. Ver destinatarios requiere subscribers:read y acceso a diálogos.

Las herramientas para preparar audiencias requieren el permiso segments:read:

  • list_audience_segments: bot_id y, opcionalmente, limit (1–100; por defecto 50) y cursor. Devuelve segments y next_cursor para la página siguiente.
  • get_audience_segment: bot_id y segment_id. Devuelve la definición, el estado y el número calculado de miembros.
  • preview_audience_segment: bot_id, definition con version y un árbol root, y limit de 1 a 20. Devuelve estimated_count, el indicador exact y una muestra sample con identificadores y nombres de visitantes y motivos de coincidencia sin valores originales. La estimación puede no ser exacta.

Para cambiar segmentos se requiere el permiso segments:write:

  • create_segment: bot_id, name y definition_json, una cadena con la definición JSON completa de versión 2. Cada llamada crea un segmento; consulta la lista antes de reintentar.
  • update_segment: bot_id, segment_id, expected_revision y al menos uno de name o definition_json. Una nueva definición sustituye la anterior por completo. Si la revisión quedó obsoleta, vuelve a leer el segmento y acuerda los cambios antes de reintentar.
  • recompute_segment: bot_id y segment_id. El estado pending indica que el recálculo está en cola, no que haya terminado.

Estas llamadas modifican datos y no aceptan un campo confirm: ejecútalas solo por indicación explícita del usuario. Cambiar la definición o recalcular puede hacer que personas entren en el segmento y activar una campaña automática configurada para ese evento, incluido el envío de correos. Comprueba las campañas asociadas antes de llamar.

El titular del token necesita acceso a analítica del bot, segmentos disponibles en su plan y la 2FA que corresponda. El segment_id obtenido puede usarse al configurar la audiencia de una campaña de email: audience_definition con kind: "segment" y ese segment_id. Estas llamadas solo leen o estiman la audiencia; no guardan el segmento, no inician una campaña ni confirman su entrega.

Para envíos basados en contenido, MCP ofrece create_content_broadcast, update_content_broadcast_draft, preflight_content_broadcast, list_content_broadcast_recipients y archive_content_broadcast. La edición y el archivo usan expected_revision; la lista de destinatarios también requiere subscribers:read y acceso a diálogos. Usa schedule_content_broadcast para programar y test_send_content_broadcast para una prueba; ambos requieren expected_revision y confirm: true. La puesta en cola no confirma la entrega.

list_campaign_templates enumera las plantillas disponibles. instantiate_campaign_template recibe bot_id, template_id y opcionalmente name, y crea un borrador sin iniciarlo ni enviar mensajes. Para el contenido están disponibles create_content_template, delete_content_template, clone_content y archive_content; eliminar y archivar requieren confirm: true.

La disponibilidad depende de la versión del servidor. Consulta tools/list antes de usar las operaciones. La lectura requiere campaigns:read; crear, editar y cambiar el estado requiere campaigns:write; publicar y reintentar requiere campaigns:publish. También se aplican los permisos del proyecto y los requisitos de plan y seguridad.

  1. create_campaign crea un borrador con bot_id y name. Consulta la revisión actual con get_campaign; usa list_campaign_versions y get_campaign_version para ver versiones y contenido.
  2. update_campaign_draft recibe bot_id, campaign_id, expected_revision y draft_json. Este último es una cadena con el objeto JSON completo del borrador: trigger, audience, settings, experiment_id, primary_goal, graph. Al guardar se sustituye todo el borrador y se vacían los campos omitidos. Si la revisión ha cambiado, vuelve a cargarlo y aplica de nuevo los cambios.
  3. Usa get_campaign_preflight para validar sin publicar. publish_campaign_draft requiere la expected_revision actual y confirm: true. Los cambios posteriores del borrador no modifican la versión publicada.
  4. set_campaign_status acepta running, paused o stopped. Iniciar con running requiere confirm: true; el primer inicio de un flujo no publicado publica su borrador. En un flujo de email también se necesitan el scope campaigns:publish y el permiso de publicación. La pausa impide nuevas entradas, pero las ejecuciones existentes continúan; stopped las detiene.
  5. retry_campaign_journey reintenta un paso fallido para subscriber_id y run_no. Envía bot_id, campaign_id y confirm: true; solo se pueden reintentar ejecuciones fallidas.

list_campaign_failures (campaigns:read) devuelve las ejecuciones fallidas recientes. Envía bot_id, campaign_id y el limit opcional de 1 a 500 (100 por defecto). No hay cursor; al alcanzar el límite la lista puede estar incompleta. Se omite el texto original del error: usa error_code y get_campaign_journey_trace.

Etiquetas (labels)

  • list_labels: labels:read
  • create_label: labels:write
  • delete_label: labels:write
  • set_label_favorite: labels:write
  • assign_user_label: labels:write; asigna una etiqueta al suscriptor (tg_user_id) usando el UUID canónico label_id. El plazo opcional ttl_days va de 0 a 106751 días; 0 significa que no caduca. Al vencer, la etiqueta se retira y se dispara el evento «Etiqueta caducada».
  • remove_user_label: labels:write; retira la etiqueta de un suscriptor mediante label_id.

Colecciones y registros (collections)

  • list_collections: collections:read
  • create_collection: collections:write
  • update_collection: collections:write
  • delete_collection: collections:write
  • list_records: collections:read
  • search_records y related_records: collections:read; búsqueda y registros relacionados con información sobre si el resultado está completo.
  • create_record: collections:write
  • update_record: collections:write
  • delete_record: collections:write
  • update_record_if: collections:write; modifica atómicamente un registro si coincide un conjunto no vacío de valores esperados. Devuelve updated, conflict o not_found.

Tratamiento de datos y elección de ramas

  • get_workflow_guide: reactions:read; esquemas actuales de acciones nuevas, límites, resultados y ejemplos de combinación.
  • transform_list: reactions:read; filtros, orden estable, eliminación de duplicados, selección de un intervalo de filas y proyección de campos.
  • aggregate_list: reactions:read; agrupa filas recibidas y calcula totales con nombres.
  • evaluate_conditions: reactions:read; comprueba condiciones en orden e indica la rama elegida sin ejecutarla.

Estas pruebas no necesitan una colección: puedes pasar los datos como JSON en data. No ejecutan reacciones ni cambian el estado del bot. update_record_if sí modifica un registro y se anota en el historial de cambios. Indica bot_id y la region necesaria; también se comprueban los derechos de la cuenta.

Las acciones de una reacción usan source como clave del contexto, mientras que estas herramientas reciben los datos de la lista directamente. Los totales se calculan sobre loaded_rows, no sobre toda la base de datos externa o la colección. Consulta Parámetros, resultados y ejemplos.

Escenarios (flows)

  • list_flows: flows:read
  • get_flow: flows:read
  • create_flow: flows:write
  • update_flow: flows:write
  • delete_flow: flows:write

Integraciones, conexiones y credenciales (integrations)

  • list_integrations: integrations:read
  • get_integration_sheets: integrations:read
  • get_integration_status: integrations:read
  • create_integration: integrations:write
  • update_integration: integrations:write
  • delete_integration: integrations:write
  • rotate_integration_token: integrations:write
  • list_connections: integrations:read
  • create_connection: integrations:write
  • test_connection: integrations:write
  • update_connection: integrations:write
  • delete_connection: integrations:write
  • list_credentials: integrations:read
  • create_credential: integrations:write
  • update_credential: integrations:write
  • delete_credential: integrations:write

CRM (crm)

CRM ofrece herramientas de lectura y las operaciones específicas de vinculación del chat con Ozma descritas abajo. Conectar, sincronizar, reintentar tareas ordinarias y resolver conflictos generales sigue requiriendo REST. No se devuelven credenciales.

  • list_crm_connections: crm:read; conexiones, proveedores, estados y capacidades.
  • get_crm_connection: crm:read; resumen seguro de una conexión.
  • get_crm_mapping: crm:read; revisión actual de la correspondencia de campos.
  • list_crm_operations: crm:read; operaciones recientes de sincronización, de más nueva a más antigua, opcionalmente de una sola conexión.
  • get_crm_operation: crm:read; una operación y sus tareas, sin el cuerpo original de solicitud de cada tarea.
  • list_crm_conflicts: crm:read; tareas que esperan una resolución manual.

La guía de Integraciones CRM explica las conexiones, la correspondencia de campos y las operaciones.

Para la integración Ozma de Gogol configurada, el propietario del proyecto puede gestionar la vinculación del contacto del chat. Todas las llamadas requieren bot_id y subscriber_id y son solo para el propietario:

  • get_ozma_chat_binding: permisos crm:read y subscribers:read; devuelve la vinculación, revision, candidatos, truncated y un evidence_token de corta duración.
  • confirm_ozma_chat_binding: permisos crm:write, crm:read, subscribers:read y subscribers:write; también recibe el contact_id elegido, expected_revision y el evidence_token sin cambios de la lectura más reciente. Úsalo solo tras la confirmación explícita del propietario y la comprobación del contacto. No se puede confirmar una lista truncada; vuelve a leer si los datos caducaron.
  • revoke_ozma_chat_binding: permisos crm:write y subscribers:write; pasa expected_revision de la lectura actual para revocar la vinculación.

La búsqueda usa el correo del perfil o, si no hay correo, el teléfono únicamente cuando el servidor tiene activado OZMA_CHAT_PHONE_BINDING_ENABLED (desactivado por defecto). Coincidir en el teléfono no acredita la identidad ni une historiales. La confirmación pone la transferencia en cola, pero no confirma su entrega. La disponibilidad depende de la versión y configuración regional.

Para errores de solicitudes del widget anteriores a la puesta en cola de tareas CRM, usa list_widget_crm_failures (crm:read, bot_id) para consultar hasta 100 registros recientes sin datos de contacto y retry_widget_crm_failure (crm:write, bot_id, failure_id) tras corregir la configuración. El reintento comprueba el consentimiento y la configuración vigentes; widget_crm_configuration_invalid y widget_consent_required indican que hay que corregir la configuración u obtener nuevo consentimiento. Una respuesta status: "queued" con operation significa que está en cola, no que se haya entregado a la CRM.

Cuando una tarea fallida de contacto del widget encuentre una coincidencia en Bitrix24, amoCRM o RetailCRM, llama a get_widget_crm_contact_candidate con bot_id y job_id (permisos crm:read y subscribers:read, además de acceso a CRM y diálogos). Compara la ficha con el visitante y obtén la confirmación explícita del propietario. Después llama a confirm_widget_crm_contact_candidate con los mismos bot_id y job_id, el remote_id devuelto y confirm: true; requiere crm:write, crm:read, subscribers:read y subscribers:write, además de acceso a CRM y diálogos. Se vuelven a comprobar el contacto y el consentimiento vigente. Un status: "queued" correcto significa que la operación está en cola, no que se haya entregado a la CRM.

Para configurar solicitudes del widget, usa una conexión Bitrix24, amoCRM o RetailCRM activa. list_widget_crm_pipelines (crm:read, bot_id, connection_id) devuelve pipelines con sus etapas statuses y current_revision. Para activar o modificar el envío, llama a set_widget_crm_trigger (crm:write) con los mismos identificadores, expected_revision de una lectura actual, enabled: true y los valores pipeline_id y status_id elegidos. Para desactivarlo, envía enabled: false y expected_revision; el embudo y la etapa son opcionales. La respuesta contiene revision y enabled. Si cambió la revisión, vuelve a leer la configuración antes de reintentar. En RetailCRM, pipeline_id es el código de la tienda y status_id es el estado del pedido. La búsqueda telefónica puede ser incompleta; revisa y confirma el contacto en la CRM.

La búsqueda telefónica de amoCRM puede ser incompleta. Si no se encuentra el contacto, se detiene la creación automática: crea o corrige la ficha en amoCRM, repite la búsqueda y confirma la coincidencia. La vinculación reduce duplicados, pero no los evita ante cambios externos o retrasos de indexación.

El embudo de la solicitud debe coincidir con el ya seleccionado en la correspondencia CRM: esta llamada no cambia un embudo existente por otro. Se conservan las demás correspondencias. Activar este flujo para otras CRM aún no está disponible.

Notificaciones del navegador y SDK de cliente (web_push, customer_sdk)

MCP permite activar Web Push, modificar su configuración y enviar notificaciones de prueba. La rotación del secreto de identidad y la revocación de dispositivos requieren REST. Las herramientas nunca devuelven la clave privada VAPID, la dirección de una suscripción push, el secreto de identidad ni el token push de un dispositivo.

  • enable_web_push: web_push:write. Envía bot_id, subject y navigation_origins, y opcionalmente quiet_hours. La primera activación crea las claves VAPID; las llamadas posteriores conservan las existentes. Se requieren permisos de gestión de Web Push y de secretos de integraciones y las comprobaciones 2FA aplicables; la creación de claves está limitada por frecuencia. No se devuelve la clave privada.
  • test_web_push: web_push:write. Envía bot_id, subscription_id, content_document_id, content_version, el payload de la notificación y la confirmación obligatoria confirm: true. Web Push debe estar activado, el suscriptor debe haber dado su consentimiento y la versión del documento push debe estar publicada. Se requieren el permiso web_push.write y las comprobaciones 2FA aplicables. La respuesta contiene message_id y status: "queued"; estar en cola no confirma la entrega. Cada llamada repetida crea un mensaje nuevo.

Para preparar un documento push publicado, usa create_push_content_draft (bot_id, name, blocks y settings opcionales), después update_push_content_draft (bot_id, document_id, version, expected_revision name opcional y los blocks y settings completos) y publish_push_content (bot_id, document_id, version, expected_revision). Obtén la versión y revisión actuales con get_content; usa list_content con kind: "push" para enumerar documentos push. Los cambios requieren el scope content:write, el permiso reactions para miembros y las comprobaciones 2FA aplicables. Crear, modificar y publicar no envía ninguna notificación. La actualización reemplaza por completo blocks y settings.

  • update_web_push_config: web_push:write. Envía bot_id y los campos que quieras cambiar: subject, navigation_origins, quiet_hours y/o enabled. Solo se modifican los campos enviados y se conservan las claves VAPID. Requiere una configuración existente, permiso de gestión de Web Push y las comprobaciones de seguridad aplicables.
  • get_web_push_config: web_push:read; configuración Web Push sin secretos.
  • get_web_push_status: web_push:read; estado de activación de las notificaciones del navegador.
  • get_web_push_report: web_push:read; recuentos de suscripciones y recibos.
  • list_web_push_subscriptions: web_push:read; hasta 100 suscripciones recientes del bot. Indica bot_id; la respuesta puede incluir el identificador del suscriptor, datos del navegador y estado del consentimiento, pero no la dirección del servicio push ni las claves.
  • get_customer_sdk_status: customer_sdk:read; estado de activación del proyecto SDK móvil.
  • get_customer_sdk_report: customer_sdk:read; recuentos de instalaciones y tokens push.

La lectura de datos de Web Push requiere el permiso web_push.read del bot. La lectura de datos del SDK de cliente requiere customer_sdk.read.

Consulta Notificaciones del navegador y SDK de cliente para interpretar estos números.

Rotar las claves VAPID

Las dos llamadas a rotate_web_push_keys requieren una configuración de Web Push existente, el scope web_push:write y el permiso web_push.write del bot. Si el proyecto exige 2FA, el titular del token debe activarla.

  1. Envía bot_id sin confirm o con confirm: false. La respuesta incluye el número de suscripciones activas en active_subscriptions y confirmation_required: true. La vista previa mantiene las claves y suscripciones y no consume el límite de rotación.
  2. Envía el mismo bot_id con confirm: true cuando aceptes que todas las suscripciones activas caduquen y que los navegadores afectados tengan que suscribirse de nuevo. Para confirmar también hace falta el permiso integrations.secrets del bot y un token de acceso personal (PAT) emitido en la región del proyecto. Se aplica el límite existente de operaciones sobre claves por bot, compartido con REST. La respuesta incluye config sin la clave privada y el número real de suscripciones caducadas en expired_subscriptions.

La herramienta está disponible tras desplegar en la región del proyecto la versión del servidor que la incluye. Comprueba que rotate_web_push_keys aparezca en tools/list.

Archivos multimedia (media)

  • list_media_assets: media:write. Envía bot_id y, opcionalmente, limit (1–100, 50 por defecto) y el cursor de la respuesta anterior. Devuelve los archivos de la biblioteca, in_use y next_cursor; excluye los adjuntos de chats y correos.
  • delete_media_asset (media:write). Envía bot_id, asset_id y confirm: true. Requiere el permiso de reacciones (reactions) y la función image_storage del plan. Si el archivo está en uso, incluida la base de conocimiento, devuelve media_in_use. La entrada se elimina de la biblioteca de inmediato (deleted: true). La limpieza se pone en cola (blob_cleanup_queued: true) y elimina el archivo almacenado solo si ya no quedan otras referencias.
  • upload_media: media:write
  • get_media: media:write
  • download_media: media:write; descarga el archivo codificado en base64 ({mime, size_bytes, data_base64}), por ejemplo para subirlo a otro bot con upload_media. Rechaza archivos de más de 2 MB.

Si el esquema de upload_media en tools/list admite launcher_icon, envía bot_id, kind: "launcher_icon" y los bytes de la imagen codificados en Base64 en data_base64. El servidor identifica PNG, JPEG y WebP por el contenido del archivo. Se admiten hasta 64 KiB (65 536 bytes). Para subir el archivo hacen falta media:write, el permiso reactions para miembros del proyecto y la función image_storage en el plan del propietario del bot.

Para aplicar el icono, guarda el id devuelto en experience.launcher.customIconMediaId mediante update_widget_settings. Obtén experience y revision con get_widget_settings, conserva los demás ajustes de experience y pasa revision como expected_revision. Consulta la configuración del icono de apertura del widget.

Plantillas (templates)

  • list_templates: templates:read
  • delete_template: templates:write
  • create_template_from_bot: templates:write
  • apply_template: templates:write

Suscriptores, chats y diálogos (subscribers)

  • list_subscribers: subscribers:read; paginación offset/limit, búsqueda, filtros por etiquetas y is_blocked=true|false. Cada registro incluye is_blocked y blocked_at si la persona bloqueó el bot.
  • list_chats: subscribers:read
  • list_dialogs: subscribers:read; conversaciones de la bandeja del operador con suscriptor, plataforma, vista previa del último mensaje y última actividad; paginación por cursor/next_cursor.
  • read_dialog: subscribers:read; mensajes de una conversación, con páginas anteriores mediante before_id. El meta de audio o vídeo transcrito contiene transcript_status, transcript y transcript_error.
  • send_dialog_message: subscribers:write; envía texto como operador, respeta la ventana de 24 horas de WhatsApp y el enrutamiento por canal. El consumo se imputa al propietario del token.
  • edit_dialog_message: subscribers:write; Sustituye el texto del mensaje o el pie de un archivo multimedia compatible. El valor de text debe contener texto.
  • delete_dialog_message: subscribers:write; Elimina el mensaje. Incluye confirm=true para confirmar la eliminación.
  • send_dialog_reaction: subscribers:write; envía una reacción preparada del bot. Equivale al botón «enviar reacción» del chat del operador. Rutas REST con el mismo permiso: POST /api/bots/{botID}/users/{userID}/dialog/messages, que exige Idempotency-Key, y POST /api/bots/{botID}/users/{userID}/dialog/reactions con {"reaction_id": "…"}.
  • transcribe_dialog_message: subscribers:write; inicia u obtiene la transcripción de audio o vídeo. Es idempotente: la primera llamada crea una tarea ({"status":"pending"}); repite la llamada hasta obtener {"status":"done","text":…}. Una transcripción fallida se reinicia automáticamente. Requiere la integración Reconocimiento de voz del bot.

En ambas llamadas incluye bot_id y tg_user_id. Usa el id del mensaje devuelto por read_dialog como message_id. Si hace falta identificar la conversación, añade channel_id y subscriber_id.

El titular del token necesita el permiso de conversaciones del bot (dialogs) y debe tener activada la 2FA si el bot la exige. Estas acciones solo se aplican a mensajes salientes ya entregados en Telegram, VK y el widget web. La operación disponible depende del canal, del tipo de mensaje y del tiempo transcurrido desde su envío.

Las herramientas aparecerán en tools/list cuando se despliegue la actualización del backend.

Responder en una conversación de soporte

send_support_message pone en cola una respuesta de texto en la última conversación del suscriptor canónico. Envía bot_id, text, el subscriber_id canónico y la revision actual de list_support_inbox como expected_dialog_revision. Incluye confirm: true y un idempotency_key con un UUID en minúsculas. Reutiliza la clave solo al reintentar el mismo envío. Evita duplicados mientras se conserve la entrada en la cola de salida.

La herramienta requiere el scope support:write, el permiso de conversaciones (dialogs) y 2FA si el proyecto la exige. Para el correo, el servidor verifica que el destinatario y el hilo pertenezcan a la conversación. En canales compatibles puedes indicar reply_to_message_id para citar un mensaje. La respuesta devuelve status: "queued" y la nueva revision. La entrega se confirma por separado.

Para devolver al agente de IA activo una conversación derivada a un operador, llama a resume_support_ai_conversation con bot_id, subscriber_id y confirm: true explícito; se requieren support:write y permisos sobre el diálogo. La respuesta contiene conversation y resumed; resumed: false significa que la repetición no cambió una conversación ya reanudada. Un estado incompatible produce un error.

Archivos adjuntos de conversaciones de soporte

Para descargar un archivo que un visitante envió a través del widget del sitio web, llama a download_support_widget_attachment con los mismos bot_id y subscriber_id que usaste en read_support_dialog. Pasa el id numérico del mensaje de la respuesta como message_id.

El token necesita el ámbito support:read y su titular necesita el permiso de conversaciones del bot (dialogs). El archivo original puede ocupar hasta 20 MiB. La respuesta contiene file_name, mime_type, size_bytes y el archivo codificado en Base64 en data_base64.

Para un adjunto de correo electrónico, llama a download_support_email_attachment con bot_id, subscriber_id, message_id y attachment_id. Usa como attachment_id el id de la entrada correspondiente del array attachments del mensaje.

La disponibilidad de las herramientas depende de la versión desplegada del servidor. Consulta tools/list.

Estado y asignación de diálogos de soporte

Las herramientas de estado del diálogo y de notas privadas solo están disponibles en las versiones del servidor donde se hayan desplegado y pueden aparecer en momentos distintos. Comprueba cada una en tools/list.

  • get_support_dialog_meta · support:read · bot_id, subscriber_id. Devuelve el estado del diálogo: bot_id, subscriber_id, status, revision, assignee_id, group_id, snoozed_until, last_activity_at, first_inbound_at, first_response_at, last_inbound_at, last_response_at, closed_at, reopened_at, reopen_count y tags (ID de etiquetas). Los campos vacíos se omiten. Un ID histórico de suscriptor que quedó tras una fusión se resuelve al suscriptor actual, y la respuesta devuelve el subscriber_id canónico.
  • update_support_dialog_meta · support:write · bot_id, subscriber_id, expected_revision y al menos un cambio: status, snoozed_until, assignee_id, group_id o assign_to_self. Los campos omitidos no cambian. La respuesta contiene el estado actualizado con la nueva revision.

Reglas de cambio:

  • status admite open, pending, closed o snoozed. open reabre un diálogo cerrado. Desde closed solo se puede pasar a open o snoozed. No se puede enviar el estado actual sin ningún otro cambio.
  • Para pasar a snoozed, indica en snoozed_until un momento futuro en formato RFC 3339. snoozed_until solo se acepta si el diálogo queda en el estado snoozed.
  • assignee_id admite el ID de un miembro de este bot. Una cadena vacía quita la asignación. assign_to_self: true asigna el diálogo al titular del token y no se puede combinar con assignee_id.
  • group_id admite el ID de un grupo de operadores de este bot. Una cadena vacía quita el grupo.

Para escribir, envía bot_id y subscriber_id como UUID canónicos: en minúsculas y con guiones. Usa el subscriber_id actual de get_support_dialog_meta o list_support_inbox. Si el suscriptor ya se fusionó con otro, la revisión leída para su ID anterior no es válida y el servidor devuelve un conflicto de revisión. En expected_revision, envía la revision actual de get_support_dialog_meta o list_support_inbox. Ante el error dialog revision conflict, vuelve a leer el diálogo y decide si el cambio sigue siendo necesario antes de repetirlo.

La lectura requiere el ámbito support:read y la escritura, support:write. El titular del token necesita el permiso de Diálogos (dialogs) del bot y, si el proyecto exige 2FA, debe tenerla activada en su cuenta.

Notas privadas en diálogos de soporte

Las notas privadas son comentarios internos de los operadores sobre un diálogo. Nunca se envían al suscriptor.

  • list_support_private_notes · support:read · bot_id, subscriber_id. Devuelve hasta 100 notas activas, de la más reciente a la más antigua. La respuesta incluye el array notes. Cada nota tiene id, bot_id, subscriber_id, author_id, body, created_at y edited_at si se editó.
  • create_support_private_note · support:write · bot_id, subscriber_id, body, expected_revision. Añade una nota en nombre del titular del token y la devuelve.
  • update_support_private_note · support:write · bot_id, subscriber_id, note_id, body, expected_revision. Sustituye el texto de la nota y establece edited_at.
  • delete_support_private_note · support:write · bot_id, subscriber_id, note_id, expected_revision. Elimina la nota de forma lógica: se marca como eliminada y deja de aparecer en la lista. Respuesta: {"status": "deleted"}.

body no puede estar vacío ni contener solo espacios y admite hasta 10 000 bytes. Envía todos los ID como UUID canónicos en minúsculas. Un subscriber_id histórico que quedó tras una fusión de suscriptores se resuelve al suscriptor actual, por lo que la respuesta puede contener otro subscriber_id. Para un diálogo o una nota desconocidos, el servidor devuelve un error de no encontrado.

El titular del token pasa a ser el autor de la nota, y su ID se devuelve en author_id. Pueden crear notas el propietario del bot y sus miembros. Solo el autor puede editar o eliminar una nota. Ni siquiera el propietario del bot puede cambiar las notas de otras personas.

Cada creación, edición o eliminación de una nota incrementa la revisión del diálogo. En expected_revision, envía la revision actual de get_support_dialog_meta o list_support_inbox. La respuesta con la nota no incluye la nueva revisión, así que vuelve a leer el diálogo antes de la siguiente escritura. Ante el error dialog revision conflict, vuelve a leer el diálogo y comprueba si el cambio sigue siendo válido.

Los permisos son los mismos que para el estado del diálogo: support:read para leer, support:write para escribir, el permiso de Diálogos (dialogs) y 2FA si el proyecto la exige.

Etiquetas de diálogos de soporte

Las etiquetas son un vocabulario común del bot, por ejemplo «pago» o «reembolso», con el que los operadores clasifican los diálogos. Estas herramientas solo aparecen después de desplegar la versión correspondiente del backend. Comprueba que cada una aparece en tools/list.

  • list_support_dialog_tags · support:read · bot_id. Devuelve el array tags: el vocabulario de etiquetas del bot ordenado por name. Cada etiqueta tiene id y name, y también color si se definió un color.
  • create_support_dialog_tag · support:write · bot_id, name y, opcionalmente, color. Se quitan los espacios al principio y al final de name; no se admite un nombre vacío ni de más de 100 caracteres. color es una cadena de hasta 32 caracteres para la visualización, por ejemplo #ff8800; el servidor no comprueba su formato. Devuelve la etiqueta con id, name y color.
  • delete_support_dialog_tag · support:write · bot_id, tag_id. Elimina la etiqueta del vocabulario y la quita de todos los diálogos. Respuesta: {"status": "deleted"}.
  • add_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Añade al diálogo una etiqueta del vocabulario.
  • remove_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Quita la etiqueta del diálogo.

add_support_dialog_tag y remove_support_dialog_tag devuelven el estado del diálogo en el formato de get_support_dialog_meta con la lista tags actualizada. Si la etiqueta ya está añadida o ya se quitó, no cambia nada y se devuelve el estado actual. Si el suscriptor todavía no tiene un diálogo guardado, add_support_dialog_tag crea un diálogo abierto con la revisión 1. Los operadores ven al instante en la bandeja de entrada cualquier cambio real de etiquetas.

En expected_revision, envía la revision actual de get_support_dialog_meta o list_support_inbox. El valor debe ser como mínimo 1; si no, el servidor devuelve expected_revision is required. Si la revisión del diálogo ya es otra, la etiqueta no cambia y se devuelve dialog revision conflict: vuelve a leer el diálogo con get_support_dialog_meta, toma el subscriber_id canónico y la revision que devuelve y decide si el cambio sigue siendo necesario. Las etiquetas no cambian la revisión: añadir, quitar o eliminar una etiqueta no incrementa revision, no se registra en el historial del diálogo y no mueve la hora de la última actividad. Por eso la respuesta conserva la misma revision, y puedes enviarla en la siguiente llamada. La comprobación de la revisión protege frente a otros cambios del diálogo posteriores a la lectura, como el estado, la asignación o las notas, pero no frente a otro operador que edite las etiquetas al mismo tiempo.

Envía todos los ID como UUID canónicos: en minúsculas y con guiones. De lo contrario, el servidor devuelve un error como tag_id must be a canonical UUID. Toma tag_id de list_support_dialog_tags y el subscriber_id actual de get_support_dialog_meta o list_support_inbox. A diferencia de las herramientas de lectura, la escritura de etiquetas no resuelve el ID histórico de un suscriptor fusionado al actual: lo rechaza con dialog revision conflict. Al fusionar suscriptores, sus etiquetas pasan al diálogo que se conserva.

La etiqueta y el suscriptor deben pertenecer al bot de bot_id. Para un bot ajeno o inaccesible, el servidor devuelve bot not found; para la etiqueta de otro bot, dialog tag not found, y para el suscriptor de otro bot, subscriber not found. Los datos de otros bots no cambian. El vocabulario y las etiquetas de los diálogos solo se pueden modificar con un token emitido para la cuenta del propietario del bot. Con un token de otra cuenta, la escritura se rechaza con permission denied.

list_support_dialog_tags requiere el ámbito support:read; las demás herramientas, support:write. Con un ámbito de solo lectura, la escritura devuelve insufficient scope. El titular del token necesita el permiso de Diálogos (dialogs) del bot; sin él, el servidor devuelve missing bot right. Si el proyecto exige 2FA, debe estar activada en la cuenta del titular del token; si no, se devuelve two_factor_enrollment_required. Al escribir, el token, el ámbito, el permiso y la 2FA se vuelven a comprobar en la misma transacción. Si el token se revocó o los permisos cambiaron, no se escribe nada y el servidor devuelve permission denied o un error de no encontrado. Cada escritura queda en el registro de acciones marcada como MCP.

Estas herramientas no tienen clave de idempotencia, así que ten en cuenta qué ocurre al repetir una llamada:

  • Puedes repetir add_support_dialog_tag y remove_support_dialog_tag con la misma expected_revision: las etiquetas no cambian la revisión, y la repetición no crea duplicados y devuelve el estado actual. Si entre intentos la revisión cambió por otro motivo, la repetición devuelve dialog revision conflict. Vuelve a leer el diálogo con get_support_dialog_meta, comprueba tags y usa el subscriber_id canónico y la revision que devuelve.
  • Repetir create_support_dialog_tag con el mismo name no crea una copia y devuelve la etiqueta con su id existente. Sin el campo color, el color actual se conserva, así que repetir es seguro. Un color explícito sustituye el color, y una cadena vacía "" lo borra.
  • Repetir delete_support_dialog_tag devuelve dialog tag not found. La eliminación no se puede deshacer: una etiqueta creada de nuevo con el mismo nombre recibe un id nuevo y hay que volver a añadirla a los diálogos.

Respuestas rápidas de operadores

Las respuestas rápidas son plantillas que el operador inserta en una respuesta escribiendo / y un atajo. Estas herramientas solo están disponibles en las versiones del servidor donde ya se desplegaron. Comprueba que aparecen en tools/list.

  • list_quick_replies · support:read · bot_id. Devuelve el array items: las plantillas compartidas del bot y las plantillas personales del titular del token. Primero aparecen las más usadas; con el mismo contador se ordenan por shortcut alfabéticamente. Cada plantilla tiene id, shortcut, title, blocks y usage_count; una personal también tiene owner_id.
  • create_quick_reply · support:write · bot_id, shortcut y, opcionalmente, title, blocks y personal. En shortcut, envía el atajo sin /; no se admite un valor vacío. blocks son bloques de mensaje en el formato del constructor de reacciones, con texto, botones, multimedia y las mismas sustituciones. Por defecto es una lista vacía. personal: true crea una plantilla personal; sin él, la plantilla se comparte con el equipo. Devuelve la plantilla guardada.
  • delete_quick_reply · support:write · bot_id, quick_reply_id. Elimina una plantilla compartida o una plantilla personal del titular del token. Respuesta: {"status": "deleted"}.
  • use_quick_reply · support:write · bot_id, quick_reply_id. Registra que un operador insertó la plantilla: incrementa usage_count en 1 y la sube en la lista. No se envía ningún mensaje al suscriptor. Respuesta: {"status": "used"}.

Las plantillas compartidas son visibles para todas las personas con el permiso de Diálogos del bot, y cualquiera de ellas puede eliminar una plantilla compartida. Una plantilla personal pertenece al titular del token que la creó: no se puede crear una plantilla personal en nombre de otro miembro. Las plantillas personales de otros miembros nunca aparecen en la lista, ni siquiera para el propietario del bot. Para ellas, igual que para un ID desconocido o mal formado, delete_quick_reply y use_quick_reply devuelven quick reply not found y el contador no cambia.

Estas herramientas no tienen clave de idempotencia, así que ten en cuenta qué ocurre al repetir una llamada:

  • Repetir create_quick_reply con personal: true y el mismo shortcut no crea una copia. Sustituye title y blocks de la plantilla personal existente y conserva su id y su usage_count.
  • Repetir create_quick_reply para una plantilla compartida crea otra plantilla con el mismo shortcut y un id nuevo. Si se perdió la respuesta de la creación, consulta primero list_quick_replies.
  • Cada llamada a use_quick_reply vuelve a incrementar el contador en 1. Llámala una vez por cada inserción de la plantilla.
  • Repetir delete_quick_reply para una plantilla ya eliminada devuelve quick reply not found.

list_quick_replies requiere el ámbito support:read; las demás herramientas, support:write. El titular del token necesita el permiso de Diálogos (dialogs) del bot y, si el proyecto exige 2FA, debe tenerla activada en su cuenta. Sin el permiso, el servidor devuelve missing bot right; sin 2FA, two_factor_enrollment_required. Al escribir, el token, el ámbito support:write, el permiso y la 2FA se vuelven a comprobar en la misma transacción. Si el token se revocó o los permisos cambiaron, no se escribe nada y el servidor devuelve permission denied o un error de no encontrado. Las plantillas de un bot archivado no se pueden modificar.

Grupos de operadores

Los grupos de operadores son conjuntos con nombre de miembros del bot a los que se enrutan los diálogos. El id de un grupo se pasa como group_id a update_support_dialog_meta y como scope u overflow_group_id a las herramientas de horarios y respuestas automáticas. Estas herramientas aparecen solo después de desplegar la versión correspondiente del backend. Comprueba cada una en tools/list.

  • list_operator_groups · support:read · bot_id. Devuelve un array groups ordenado por name. Cada grupo tiene id, name, strategy y member_ids: los ID de las cuentas de sus miembros o un array vacío. El orden de member_ids en la lista no está garantizado.
  • create_operator_group · support:write · bot_id, name y strategy opcional. Se recortan los espacios al principio y al final de name. Un nombre vacío devuelve name is required, y uno de más de 200 caracteres, name must be at most 200 characters. El nombre es único dentro del bot. strategy admite least_busy (predeterminado), round_robin o all; cualquier otro valor devuelve strategy must be least_busy, round_robin or all. Devuelve group y created.
  • delete_operator_group · support:write · bot_id, group_id. Elimina el grupo. Respuesta: {"status": "deleted", "group_id": "…"}.
  • add_operator_group_member · support:write · bot_id, group_id, owner_id. Añade un miembro del bot al grupo. Devuelve group y changed.
  • remove_operator_group_member · support:write · bot_id, group_id, owner_id. Quita la cuenta del grupo. Devuelve group y changed.

En las respuestas de escritura, group tiene los mismos campos que en la lista, con member_ids ordenados por ID. Cuando un diálogo se enruta a un grupo, least_busy lo asigna al miembro con menos diálogos abiertos asignados, y round_robin, al miembro que lleva más tiempo sin recibir una asignación. Con all, la asignación automática elige actualmente al miembro igual que con least_busy. Por MCP no se puede renombrar un grupo ni cambiar la estrategia de uno existente.

Pasa en owner_id el ID de la cuenta del propietario del bot o de un administrador del bot. Para cualquier otra cuenta, incluida una cuyo procesamiento de datos está suspendido, add_operator_group_member devuelve owner_id is not a member of this bot. Un miembro que pierde el acceso al bot sale automáticamente de sus grupos. MCP no tiene una herramienta para listar los miembros del bot: los ID de cuenta aparecen en member_ids y en assignee_id de get_support_dialog_meta. remove_operator_group_member no comprueba la pertenencia al bot.

Al eliminar un grupo también se eliminan sus reglas de enrutamiento, su horario con festivos y sus políticas de respuesta automática. Los diálogos pierden el grupo en group_id, pero conservan su operador asignado, y los horarios que usaban el grupo como overflow_group_id pierden ese ajuste. Mientras un agente de IA activo o en pausa transfiera diálogos a ese grupo, la eliminación se rechaza con operator group is the handoff target of an active or paused AI agent: cambia antes el grupo de transferencia del agente. La eliminación no se puede deshacer: un grupo creado de nuevo con el mismo nombre recibe un id nuevo, y hay que volver a configurar sus miembros, reglas y horario.

Pasa todos los ID como UUID canónicos: en minúsculas y con guiones. De lo contrario, el servidor devuelve un error como group_id must be a canonical UUID. Para un bot ajeno, archivado o inaccesible, el servidor devuelve bot not found, y para un grupo desconocido o de otro bot, operator group not found. Los grupos solo se pueden modificar con un token emitido para la cuenta del propietario del bot. Con cualquier otro token, la escritura se rechaza con bot not found o permission denied.

list_operator_groups requiere el ámbito support:read; las demás herramientas, support:write. Con un ámbito de solo lectura, la escritura devuelve insufficient scope. El titular del token necesita el permiso de Diálogos (dialogs) del bot; sin él, el servidor devuelve missing bot right. Si el proyecto exige 2FA, debe estar activada en la cuenta del titular del token; si no, se devuelve two_factor_enrollment_required. Al escribir, el token, el ámbito, el permiso y la 2FA se vuelven a comprobar en la misma transacción. Si el token se revocó o los permisos cambiaron, no se escribe nada y el servidor devuelve permission denied o bot not found. Cada escritura queda en el registro de acciones marcada como MCP.

Estas herramientas no tienen clave de idempotencia, así que ten en cuenta el comportamiento al repetir:

  • Repetir create_operator_group con los mismos name y strategy no crea una copia y devuelve el grupo existente con created: false. Sin strategy se usa least_busy. El mismo nombre con otra estrategia devuelve an operator group with this name already exists with a different strategy, y el grupo no cambia. El mismo error puede aparecer si en ese momento se está eliminando un grupo con ese nombre, así que comprueba list_operator_groups antes de repetir.
  • Repetir add_operator_group_member o remove_operator_group_member es seguro: si la cuenta ya está en el grupo o ya se quitó, nada cambia y se devuelve el group actual con changed: false.
  • Repetir delete_operator_group devuelve operator group not found.
  • operator group change conflicted with a concurrent update; retry significa que no se escribió nada y puedes repetir la misma llamada. Tras operator group could not be changed, comprueba el estado con list_operator_groups antes de repetir. account processing is suspended significa que el procesamiento de datos de la cuenta está suspendido; repetir no servirá.

Reglas de enrutamiento de soporte

Las reglas de enrutamiento asignan automáticamente un diálogo nuevo a un grupo de operadores o a un miembro concreto del bot. Estas herramientas aparecen solo después de desplegar la versión correspondiente del backend. Comprueba cada una en tools/list.

  • list_routing_rules · support:read · bot_id. Devuelve un array rules: todas las reglas del bot, activadas y desactivadas, en orden de evaluación. Las reglas se ordenan por priority y, con igual prioridad, por name.
  • create_routing_rule · support:write · bot_id, name, exactamente uno de group_id y assignee_id, y priority, enabled y match opcionales. Cada llamada crea una regla nueva. Devuelve rule.
  • update_routing_rule · support:write · bot_id, rule_id y al menos uno de name, priority, enabled, match, group_id o assignee_id. Sin cambios, el servidor devuelve nothing to update. Devuelve la rule actualizada.
  • delete_routing_rule · support:write · bot_id, rule_id. Elimina la regla. Respuesta: {"status": "deleted", "rule_id": "…"}.
  • reorder_routing_rules · support:write · bot_id, expected_rule_ids, rule_ids. Establece el orden de todas las reglas del bot y devuelve un array rules en el nuevo orden.

Una regla tiene id, bot_id, name, priority, enabled, match y uno de group_id o assignee_id. match contiene solo las condiciones definidas; en una regla sin condiciones es {}. Se recortan los espacios al principio y al final de name. Un nombre vacío devuelve name is required, y uno de más de 200 caracteres, name must be at most 200 characters. No se exige que el nombre sea único. priority es un entero en el rango de 32 bits, incluidos los negativos: cuanto menor es el valor, antes se evalúa la regla. Sin priority, una regla nueva recibe 100; sin enabled, se crea activada. Cuando create_routing_rule o update_routing_rule devuelven una regla con match.tags no vacío, la respuesta incluye también un array warnings.

Condiciones. Todas las listas de match son opcionales, y una regla coincide solo si se cumplen todas las condiciones definidas. Sin match o con un match vacío, la regla coincide con cualquier diálogo nuevo.

  • platforms: los canales de los que llegó el mensaje: tg, vk, wa, web, email, ig o fb. Basta con una coincidencia. Los valores se pasan a minúsculas; cualquier otro valor devuelve match.platforms must contain only tg, vk, wa, web, email, ig or fb.
  • keywords: subcadenas del primer mensaje entrante, sin distinguir mayúsculas y minúsculas. Basta con una coincidencia.
  • labels: nombres de etiquetas del suscriptor, distinguiendo mayúsculas y minúsculas. El suscriptor debe tener todas las etiquetas indicadas.
  • tags: ID de etiquetas de diálogo de este bot de list_support_dialog_tags. Esta condición nunca se cumple: el enrutamiento se ejecuta con el primer mensaje entrante, antes de que se pueda añadir ninguna etiqueta. La regla se guarda y warnings incluye un aviso al respecto.

Cada lista admite hasta 50 valores. Los valores de keywords y labels no pueden estar vacíos ni contener solo espacios, y tienen un límite de 200 caracteres. De lo contrario, el servidor devuelve un error de validación como match.keywords must have at most 50 entries. Una etiqueta de otro bot o desconocida devuelve dialog tag not found in this bot.

Destino. Pasa el ID de un grupo de list_operator_groups como group_id, o el ID de la cuenta del propietario o de un administrador del bot como assignee_id. Indica exactamente uno de estos campos; de lo contrario, el servidor devuelve specify exactly one of group_id or assignee_id. Un grupo desconocido o de otro bot devuelve group does not belong to this bot, y una cuenta que no es miembro del bot, assignee is not a member of this bot. Las reglas de un grupo se eliminan junto con el grupo, y las de un miembro, cuando este pierde el acceso al bot.

Cambios parciales. update_routing_rule cambia solo los campos que pasas. match se reemplaza por completo: para añadir una palabra clave, pasa el match nuevo entero, y {} quita todas las condiciones. Un group_id o assignee_id que pases reemplaza el destino y borra el otro campo, así que pasa solo uno de ellos. Si el cambio deja la regla sin destino o con dos, por ejemplo group_id: "" sin assignee_id, el servidor devuelve specify exactly one of group_id or assignee_id. Cuando cambia el destino o se pasa enabled: true, el servidor vuelve a comprobar que el destino pertenece al bot; las etiquetas se comprueban solo si se pasa match. Las reglas no tienen revisión: el cambio se escribe sobre el estado actual aunque otra persona acabe de modificar la regla.

Orden. Pasa como expected_rule_ids los ID de todas las reglas del bot, incluidas las desactivadas, en el orden actual de list_routing_rules, y como rule_ids los mismos ID en el orden deseado. Sin estos campos, el servidor devuelve expected_rule_ids is required o rule_ids is required. Si rule_ids contiene otro conjunto de ID o duplicados, devuelve invalid routing rule order: rule_ids must be a permutation of expected_rule_ids. Si después de leer la lista se añadió o eliminó una regla, o cambió el orden, la llamada no cambia nada y devuelve routing rules changed; reload and retry. Si tiene éxito, las reglas reciben las prioridades 10, 20, 30, etc. Una regla nueva con la prioridad predeterminada 100 queda detrás de las reglas con menor prioridad, y entre las de igual prioridad su posición la decide name.

Cómo se aplican las reglas. El enrutamiento se ejecuta una sola vez: con el primer mensaje entrante de un diálogo que aún no tiene ni operador ni grupo. El servidor evalúa las reglas activadas en orden y aplica la primera que coincide. Para un grupo, el operador se elige según su estrategia, teniendo en cuenta los horarios y overflow_group_id. Para un miembro se aplica el horario del bot y, si el miembro no está disponible, el diálogo puede recibirlo otro miembro de uno de sus grupos. Si no hay ningún operador disponible para la primera regla que coincide, las reglas siguientes no se evalúan y el diálogo queda en la cola de no asignados. Lo mismo ocurre si no coincide ninguna regla. Crear, cambiar, eliminar o reordenar reglas no afecta a los diálogos ya asignados: conservan su asignación.

Pasa todos los ID como UUID canónicos: en minúsculas y con guiones. De lo contrario, el servidor devuelve un error como rule_id must be a canonical UUID. Para un bot ajeno, archivado o inaccesible, el servidor devuelve bot not found, y para una regla desconocida o de otro bot, routing rule not found. Las reglas solo se pueden modificar con un token emitido para la cuenta del propietario del bot. Con cualquier otro token, la escritura se rechaza con bot not found o permission denied.

list_routing_rules requiere el ámbito support:read; las demás herramientas, support:write. Con un ámbito de solo lectura, la escritura devuelve insufficient scope. El titular del token necesita el permiso de Diálogos (dialogs) del bot; sin él, el servidor devuelve missing bot right. Si el proyecto exige 2FA, debe estar activada en la cuenta del titular del token; si no, se devuelve two_factor_enrollment_required. Al escribir, el token, el ámbito, el permiso y la 2FA se vuelven a comprobar en la misma transacción. Si el token se revocó o los permisos cambiaron, no se escribe nada y el servidor devuelve permission denied o bot not found. Cada escritura queda en el registro de acciones marcada como MCP.

Estas herramientas no tienen clave de idempotencia, así que ten en cuenta el comportamiento al repetir:

  • Repetir create_routing_rule crea otra regla con un id nuevo, aunque los campos sean iguales. Si se perdió la respuesta de una creación, comprueba primero list_routing_rules.
  • Repetir update_routing_rule vuelve a escribir los valores pasados. Si otra persona cambió la regla entre intentos, la repetición sobrescribe esos campos. Si se perdió la respuesta, comprueba primero la regla en list_routing_rules.
  • Repetir delete_routing_rule devuelve routing rule not found. La eliminación es irreversible: una regla creada de nuevo recibe un id nuevo.
  • Tras un reorder_routing_rules correcto, repetirlo con los mismos expected_rule_ids suele devolver routing rules changed; reload and retry, porque el orden ya es otro. El mismo error aparece si otra persona cambió las reglas. En ambos casos, vuelve a leer list_routing_rules, comprueba el orden y solo entonces repite con los nuevos expected_rule_ids.
  • Tras routing rule could not be changed, comprueba el estado con list_routing_rules antes de repetir. account processing is suspended significa que el procesamiento de datos de la cuenta está suspendido; repetir no servirá.

Lectura de diálogos de operadores

Estas herramientas usan los mismos contadores de no leídos que la bandeja de operadores: muestran cuántos mensajes entrantes aún no ha leído el titular del token y marcan un diálogo como leído, igual que al abrirlo en la consola. Las herramientas aparecen solo después de desplegar la versión correspondiente del backend. Comprueba cada una en tools/list.

  • get_dialog_unread_summary · support:read · bot_id. Devuelve {"items": [...], "count": N}: los no leídos del titular del token en los diálogos del bot, incluido el email. Los diálogos sin mensajes entrantes no leídos no aparecen. Cada fila tiene user_id y unread, además de channel_id, scope_channel_id y subscriber_id cuando no están vacíos. Un usuario puede aparecer en varias filas, una por canal. No hay paginación y el orden de las filas no está garantizado.
  • get_dialog_read_state · support:read · bot_id, user_id, channel_id y subscriber_id opcionales. Devuelve el estado de lectura de un diálogo sin cambiar nada.
  • mark_dialog_read · support:write · bot_id, user_id, channel_id, subscriber_id y last_read_message_id opcionales. Marca el diálogo como leído para el titular del token y devuelve el nuevo estado.

La respuesta de get_dialog_read_state y mark_dialog_read contiene unread (número de mensajes entrantes no leídos), first_unread_message_id (ID del primer mensaje no leído en el orden del historial; no aparece si todo está leído), last_read_message_id (la marca propia del titular del token, o 0 si no ha leído el diálogo) y shared (true si al titular del token se le aplica la lectura compartida).

Cómo indicar el diálogo. user_id es el ID del usuario del diálogo como cadena decimal. Tómalo de user_id en una fila del resumen o de tg_user_id_str en list_dialogs y pásalo sin cambios como cadena: el valor numérico tg_user_id pierde precisión en ID grandes. Los ceros a la izquierda, el signo +, los exponentes y 0 se rechazan con user_id must be a non-zero decimal integer string.

Para elegir un diálogo del resumen, pasa su scope_channel_id como channel_id, no el campo channel_id de la fila. En el resumen, channel_id está vacío en un diálogo antiguo de Telegram sin canal asociado, mientras que scope_channel_id indica el canal al que pertenecen los mensajes y la marca de lectura. Para una coincidencia exacta, añade subscriber_id de la misma fila. No se puede pasar sin channel_id: el servidor devuelve subscriber_id requires channel_id. Si una fila no tiene scope_channel_id, no pases ni channel_id ni subscriber_id.

Sin channel_id ni subscriber_id, las herramientas trabajan con el diálogo antiguo (legacy) del canal principal de Telegram del bot, como la ruta de la consola sin canal. Es la misma marca que con el channel_id de ese canal de Telegram. list_dialogs no devuelve el ID del canal, así que con tg_user_id_str solo se llega a este diálogo. Los diálogos de un usuario en distintos canales se leen por separado: una marca en un canal no cambia el contador de otro.

Pasa los UUID en forma canónica: en minúsculas y con guiones. De lo contrario, el servidor devuelve un error como channel_id must be a canonical UUID. Si el canal pertenece a otro bot, el usuario no tiene diálogo en ese canal, subscriber_id pertenece a otro diálogo o el suscriptor ya se fusionó con otro, se devuelve dialog scope not found. Después de fusionar suscriptores, vuelve a obtener la fila del resumen. invalid dialog scope indica una combinación no válida de channel_id y subscriber_id.

Marcar como leído. Sin last_read_message_id, o con 0, todo el diálogo se marca como leído en el momento de la llamada. Para marcarlo hasta un punto concreto, pasa el id de un mensaje de este diálogo, por ejemplo de read_dialog: los mensajes posteriores en el orden del historial siguen sin leer. Un mensaje de otro diálogo o canal devuelve message not found in this dialog, y un valor negativo, last_read_message_id must not be negative. La marca solo avanza: si el mensaje es anterior a la marca actual, esta no cambia y se devuelve el estado actual.

La marca pertenece al titular del token, no al propietario del bot, y solo cambia sus contadores. No se envía nada al cliente ni se entrega confirmación de lectura, y los mensajes y el estado del diálogo de soporte no cambian. Si la marca avanza, las consolas de operadores abiertas actualizan sus contadores.

Lectura compartida. Si la lectura compartida está activada para todo el bot o en los ajustes personales del titular del token (consulta Soporte), unread, first_unread_message_id y el resumen se calculan desde la última marca de cualquier operador, y shared es true. Incluso en este modo, last_read_message_id sigue siendo la marca propia del titular del token. Por eso mark_dialog_read también puede borrar el contador de los compañeros a los que se aplica la lectura compartida. Sin ella, la marca solo afecta al titular del token.

Acceso y errores. get_dialog_unread_summary y get_dialog_read_state requieren el ámbito support:read, y mark_dialog_read, support:write. Con un ámbito de solo lectura, marcar devuelve insufficient scope. El titular del token necesita el permiso de Diálogos (dialogs) del bot; sin él, el servidor devuelve missing bot right. Si el proyecto exige 2FA, debe estar activada en la cuenta del titular del token; si no, se devuelve two_factor_enrollment_required. Para un bot ajeno, archivado o inaccesible se devuelve bot not found. Solo se pueden marcar diálogos como leídos con un token emitido para la cuenta del propietario del bot. Con cualquier otro token, la escritura se rechaza con bot not found o permission denied. Al marcar, el token, el ámbito, el permiso y la 2FA se vuelven a comprobar en la misma transacción. Si el token se revocó o los permisos cambiaron, no se escribe nada y se devuelve permission denied o bot not found. Cada llamada a mark_dialog_read, incluso rechazada, queda en el registro de acciones marcada como MCP. Las lecturas no se registran.

Los errores unread summary is temporarily unavailable, dialog read state is temporarily unavailable y dialog could not be marked read son temporales. mark_dialog_read no tiene clave de idempotencia, pero repetirlo es seguro: la marca nunca retrocede y una repetición con el mismo last_read_message_id no cambia nada. Una repetición sin last_read_message_id también marca los mensajes que llegaron entre los intentos.

Horarios, festivos y respuestas automáticas de soporte (support)

Comprueba la disponibilidad en tools/list tras actualizar el servidor. El titular del token personal necesita el permiso de Diálogos (dialogs) del bot. Si el proyecto exige 2FA, actívala en la cuenta del titular.

Envía bot_id en todas las llamadas. Usa bot o el UUID de un grupo de operadores de ese bot como scope.

  • list_support_schedules · support:read · bot_id. Lista los horarios del bot y de sus grupos de operadores junto con sus revisiones.
  • list_support_holidays · support:read · bot_id, scope. Lista los festivos del horario y devuelve su revisión actual.
  • list_support_auto_replies · support:read · bot_id. Lista las reglas de respuesta automática del bot y de sus grupos junto con sus revisiones.
  • preview_support_availability · support:read · bot_id, scope, from, to. Muestra el estado en from y las transiciones hasta to según el horario y los festivos guardados. Usa marcas de tiempo RFC 3339. El intervalo debe ser positivo y no superar los 31 días. La vista previa no guarda cambios ni envía mensajes. La respuesta incluye hasta 512 entradas en transitions, con at, state y reason.
  • upsert_support_schedule · support:write · bot_id, scope, timezone, weekly_intervals, enabled, expected_revision. Crea o reemplaza un horario. Indica una zona horaria IANA, por ejemplo Europe/Belgrade, y todos los intervalos semanales. Usa weekday (0 para domingo y 6 para sábado), start_minute y end_minute en minutos desde la medianoche local. El campo opcional overflow_group_id identifica un grupo del mismo bot.
  • replace_support_holidays · support:write · bot_id, scope, holidays, expected_revision. Reemplaza todos los festivos de un horario existente. Cada entrada usa local_date (YYYY-MM-DD), kind (closed o custom), name e intervals. Usa intervalos vacíos para closed e indica start_minute y end_minute en cada intervalo de custom. Pasa holidays: [] para vaciar la lista.
  • upsert_support_auto_reply · support:write · bot_id, scope, state, content_document_id, content_version, interval_seconds, enabled, expected_revision. Guarda una regla para el horario working o non_working. Usa una versión publicada de un documento de contenido sin archivar del mismo bot e indica el intervalo entre respuestas en segundos (1–2 678 400).

Todas las escrituras requieren expected_revision. Usa 0 solo al crear un horario o una regla de respuesta automática. Para actualizar, usa la revision actual de una lectura. El horario y sus festivos comparten una revisión que cambia al actualizar cualquiera de los dos. Cada regla tiene su propia revisión para la combinación de scope y state. Si la revisión está obsoleta, vuelve a leer los datos y aplica los cambios a la versión más reciente.

Estas herramientas configuran el funcionamiento del soporte. Para gestionar la disponibilidad del propio widget web, usa get_widget_settings y update_widget_settings.

Estadísticas y análisis (stats)

get_support_analytics devuelve el informe de soporte para el periodo elegido; get_support_analytics_details devuelve el detalle paginado de una métrica con cursor firmado. Ambos requieren stats:read y permiso de análisis del proyecto; el periodo no puede superar 366 días.

  • get_stats: stats:read
  • get_stats_summary: stats:read
  • get_stats_recent: stats:read
  • get_stats_log: stats:read
  • get_reaction_health: stats:read
  • get_analytics: stats:read
  • get_analytics_chats: stats:read
  • get_site_widget_analytics: stats:read
  • get_site_popup_analytics: stats:read
  • get_funnel: stats:read

Ambas herramientas requieren el permiso de Analítica del proyecto y el scope stats:read. Envía bot_id, from y to con los límites en formato RFC 3339. El inicio se incluye y el final se excluye: [from, to). El período debe ser positivo y no superar 366 días; los días del resultado usan UTC.

get_site_widget_analytics devuelve las vistas de páginas recibidas, los identificadores de visitantes observados durante todo el período, los diálogos web activos y los mensajes entrantes, además de los datos por día. Las vistas pueden incluir eventos del servidor y los identificadores no representan necesariamente personas únicas. get_site_popup_analytics devuelve los recuentos de impresiones, impresiones visibles, interacciones y conversiones por popup y por día UTC. Son recuentos de eventos, no de personas. Una impresión visible significa que al menos la mitad del popup estuvo en pantalla dos segundos seguidos con la pestaña visible; no demuestra que se haya leído el texto. Ninguna de las herramientas devuelve datos financieros.

Impresiones y conversiones de popups

  • get_popup_report (popups:read + subscribers:read) – Métricas diarias de un popup (days).

  • get_site_popup_analytics (stats:read) – Totales por popup para el período y totales diarios de todos los popups (popups, days).

  • measured_shown. Número de impresiones distintas registradas con un impression_id válido y un identificador de contacto (subscriber_id).

  • converted_impressions. Número de esas impresiones con una conversión asociada. Cada impresión se cuenta como máximo una vez.

  • impression_conversion_rate = converted_impressions / measured_shown

  • impression_coverage = measured_shown / shown

Las dos tasas son proporciones de 0 a 1. Si el denominador es cero, el valor es null.

La conversión debe coincidir con el identificador de impresión, el proyecto, el popup, la variante y el contacto. Puede registrarse desde 60 segundos antes de la impresión hasta menos de 24 horas después. Se atribuye al día UTC de la impresión.

Los eventos históricos sin identificador de impresión siguen contando en shown, viewed, interacted y converted según la hora del evento. No pueden vincularse a una impresión medida. Si solo hay impresiones sin medición en el período, la cobertura es 0 y la tasa de conversión por impresión es null.

Experimentos compartidos (experiments)

  • list_experiments: experiments:read
  • get_experiment: experiments:read
  • get_experiment_report: experiments:read

Estas herramientas son de solo lectura. Devuelven la definición inmutable o el informe de una versión del experimento. El informe separa las monedas e indica el modelo de atribución elegido. Las herramientas no asignan variantes, registran eventos, cambian el estado ni eligen ganadores.

{
  "name": "get_experiment_report",
  "arguments": { "bot_id": "<bot-id>", "experiment_id": "<experiment-id>", "version": 2 }
}

Los embudos de eventos guardados todavía solo están disponibles por REST. get_funnel, mencionado arriba, devuelve un embudo automático de estadísticas, no la definición de un embudo guardado ni su cohorte. Para estos casos, usa los endpoints REST acotados de la guía de embudos.

Facturación: lectura (billing)

  • get_balance: billing:read
  • list_tariffs: billing:read
  • get_transactions: billing:read

Si el token pertenece a otra cuenta, los tres requieren el derecho billing.read. Si falta, devuelven permission denied: missing cabinet right.

Envío de mensajes

  • send_message: broadcasts:write; envía un mensaje en nombre del bot. El consumo se imputa automáticamente al propietario del token.

Recursos

Además de herramientas, el servidor ofrece recursos para consultar estructuras sin adivinarlas:

  • mybot://openapi.yaml: especificación OpenAPI completa, igual que /openapi.yaml.
  • mybot://reference: referencia compacta de herramientas y permisos, dirección base, paginación, errores y límites.
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow y mybot://schemas/collection: esquemas JSON para crear reacciones, escenarios y colecciones con los campos correctos.
  • mybot://bots: lista dinámica de tus bots sin llamar a una herramienta.

Prompts

Son tareas preparadas que un cliente MCP puede ofrecer como comandos:

  • setup_autoresponder: crear un bot de respuestas automáticas; recibe bot y tema o preguntas.
  • segment_broadcast: difundir a un segmento de etiquetas; recibe bot, etiquetas y reacción o texto.
  • diagnose_reaction: averiguar por qué no se activa una reacción; consulta la reacción, su estado y el orden.
  • import_from_sambot: importar un paquete SamBot y comprobar el resultado.
  • weekly_report: resumir las estadísticas y el análisis del bot durante un período.

Cuándo usar MCP o REST

  • Para desarrollar una integración, sincronización, script o panel propio, usa REST.
  • Para conectar GetMyBot con un asistente de IA compatible con MCP, usa /mcp.

Ambas interfaces usan el mismo token y respetan los derechos de su propietario. Si falta una herramienta, consulta el endpoint REST correspondiente en la referencia interactiva.

La disponibilidad de funciones se comprueba igual en REST y MCP. Copilot, Flow Intelligence, Explainable Replay y Vertical Playbooks solo funcionan en las cuentas donde están activados. Cambiar de interfaz no da acceso a una función desactivada.

Herramientas de IA y escenarios

FunciónHerramientasPermisos
Managed AIinvoke_managed_ai, get_managed_ai_usagemanaged_ai:invoke, managed_ai:usage:read
Copilotcreate_copilot_proposal, get_copilot_proposal, validate_copilot_proposal, simulate_copilot_proposal, apply_copilot_proposal, reject_copilot_proposalcopilot:use y permisos de lectura y edición de recorridos
Flow Intelligenceget_flow_intelligence_policy y herramientas de vista previa, actualización y recálculoanalytics:read, journey:edit
Replaylist_execution_traces, get_execution_trace, simulate_execution_trace, capture_regression_fixture, list_regression_fixtures, get_regression_fixture, run_regression_fixture, list_replay_runsjourney:read/edit
Playbookslist_vertical_playbooks y herramientas de preparación, comprobación, instalación y actualización; los KPI siguen disponibles solo por RESTpermisos de lectura y escritura de plantillas, bots y reacciones
Onboardingstart_outcome_onboarding, update_outcome_onboarding, complete_outcome_onboardingpermisos de bots, plantillas y reacciones
Metalist_meta_connections, start_meta_authorization, refresh_meta_assets y herramientas para comprobar, elegir, conectar y desconectar activospermisos de integraciones y bots

Las operaciones que cambian datos se registran con la marca MCP y el ID del token personal. OAuth devuelve una dirección para abrirla en el navegador. Los endpoints de retorno y los webhooks entrantes no se invocan como herramientas. Los agentes de los usuarios no pueden acceder a claves de proveedores, enrutamiento ni conciliación de cargos.

Qué sigue

Reglas de seguimiento visual

list_tracking_rules requiere tracking:read; crear, modificar y eliminar requieren tracking:write, permiso para gestionar reacciones y 2FA cuando corresponda. Una regla activa recopila eventos y valores especificados en las páginas coincidentes; revisa su configuración antes de activarla. Para modificar o eliminar, usa la revision actual de la lista como expected_revision; ante un conflicto, vuelve a consultar la regla. Los campos omitidos no cambian.

  • list_tracking_rules: bot_id
  • create_tracking_rule: bot_id, name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • update_tracking_rule: bot_id, rule_id, expected_revision; name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • delete_tracking_rule: bot_id, rule_id, expected_revision