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:readget_bot:bots:readvalidate_bot_token:bots:writeconnect_bot:bots:writeupdate_bot:bots:writedelete_bot:bots:writesync_bot:bots:writechange_bot_token:bots:writetransfer_bot:bots:writeget_bot_settings:settings:readupdate_bot_settings:settings:write; incluyetest_user_ids, usuarios de prueba sin cargosget_widget_email_readiness:settings:read. Envíabot_idpara comprobar la configuración de respuestas del widget por correo.senderConfiguredindica si se encontró un remitente;transportStatuspuede serconfigured,not_configuredounknown. Es un estado de configuración y no confirma la entrega.get_widget_settings:settings:readupdate_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_settingsdevuelve el diseño, botón de apertura, ventana del chat, saludo, formulario previo, horario, comportamiento, sitios permitidos (origins),widgetKeyy revisiónrevision. Para guardar, pasa esa revisión comoexpected_revisionaupdate_widget_settings. Si alguien cambió los ajustes, la actualización se rechazará. No usesupdate_bot_settingsen su lugar: escribirwidget_experiencepor 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 conplatform(tg/wa/vk/web),external_id, nombre, estado ycallback_url.connect_channel:bots:write; conecta WhatsApp, VK o el widget web. Paraplatform: "web"no se necesitan credenciales, pero sí una listaoriginsno 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 estadoAPPROVED,REJECTEDoPAUSED.delete_wa_template:bots:write; elimina una plantilla.
Los canales de Telegram se conectan con
connect_bot.connect_channelsirve parawa,vkyweb. Las categorías de plantillas sonMARKETING,UTILITYyAUTHENTICATION.create_wa_templateenvía inmediatamente el borrador a Meta, pero la revisión es asíncrona. Consulta el estado conlist_wa_templatesy, si hace falta, actualiza el catálogo consync_wa_templates.
La respuesta de
connect_channelparaplatform: "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, usaget_widget_settingsyupdate_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:readget_reaction:reactions:readcreate_reaction:reactions:writeupdate_reaction:reactions:writedelete_reaction:reactions:writeimport_reactions:reactions:writetest_formula:reactions:write; prueba una fórmula avanzada con un texto de ejemplo. Campos:bot_id,formulaysample; en REST este último se llamasample_text. El contexto está vacío: no se sustituyenctxni los parámetros; el texto de ejemplo se puede usar como{text}o{answer}.reorder_reaction:reactions:writeget_reaction_links:reactions:readlist_reaction_folders:reactions:readcreate_reaction_folder:reactions:writeupdate_reaction_folder:reactions:writedelete_reaction_folder:reactions:writeadd_reaction_to_folder:reactions:writeremove_reaction_from_folder:reactions:writeadd_reactions_to_folder:reactions:write
import_reactionscrea 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; admitepaidy un segmento por etiquetas opcionales.get_broadcast:broadcasts:write; en las difusiones iniciadas desde una reacción constart_broadcast, el informe incluyeblocked: bloqueos atribuidos a la difusión durante las 24 horas posteriores a la entrega.pause_broadcast:broadcasts:writeresume_broadcast:broadcasts:writecancel_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íabot_id. La respuesta incluyemodey, para SMTP propio, los ajustes yversion; nunca devuelve la contraseña. -
put_email_smtp(settings:write): envíabot_id,host,port,security(starttlsotls),username,envelope_fromypassword. Al crear, omiteexpected_version; al modificar, indica la versión deget_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íabot_idy elexpected_versionactual 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_idy, opcionalmente,limit(1–100; por defecto 50) ycursor. Devuelvesegmentsynext_cursorpara la página siguiente.get_audience_segment:bot_idysegment_id. Devuelve la definición, el estado y el número calculado de miembros.preview_audience_segment:bot_id,definitionconversiony un árbolroot, ylimitde 1 a 20. Devuelveestimated_count, el indicadorexacty una muestrasamplecon 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,nameydefinition_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_revisiony al menos uno denameodefinition_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_idysegment_id. El estadopendingindica 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.
create_campaigncrea un borrador conbot_idyname. Consulta la revisión actual conget_campaign; usalist_campaign_versionsyget_campaign_versionpara ver versiones y contenido.update_campaign_draftrecibebot_id,campaign_id,expected_revisionydraft_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.- Usa
get_campaign_preflightpara validar sin publicar.publish_campaign_draftrequiere laexpected_revisionactual yconfirm: true. Los cambios posteriores del borrador no modifican la versión publicada. set_campaign_statusaceptarunning,pausedostopped. Iniciar conrunningrequiereconfirm: true; el primer inicio de un flujo no publicado publica su borrador. En un flujo de email también se necesitan el scopecampaigns:publishy el permiso de publicación. La pausa impide nuevas entradas, pero las ejecuciones existentes continúan;stoppedlas detiene.retry_campaign_journeyreintenta un paso fallido parasubscriber_idyrun_no. Envíabot_id,campaign_idyconfirm: 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:readcreate_label:labels:writedelete_label:labels:writeset_label_favorite:labels:writeassign_user_label:labels:write; asigna una etiqueta al suscriptor (tg_user_id) usando el UUID canónicolabel_id. El plazo opcionalttl_daysva 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 mediantelabel_id.
Colecciones y registros (collections)
list_collections:collections:readcreate_collection:collections:writeupdate_collection:collections:writedelete_collection:collections:writelist_records:collections:readsearch_recordsyrelated_records:collections:read; búsqueda y registros relacionados con información sobre si el resultado está completo.create_record:collections:writeupdate_record:collections:writedelete_record:collections:writeupdate_record_if:collections:write; modifica atómicamente un registro si coincide un conjunto no vacío de valores esperados. Devuelveupdated,conflictonot_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:readget_flow:flows:readcreate_flow:flows:writeupdate_flow:flows:writedelete_flow:flows:write
Integraciones, conexiones y credenciales (integrations)
list_integrations:integrations:readget_integration_sheets:integrations:readget_integration_status:integrations:readcreate_integration:integrations:writeupdate_integration:integrations:writedelete_integration:integrations:writerotate_integration_token:integrations:writelist_connections:integrations:readcreate_connection:integrations:writetest_connection:integrations:writeupdate_connection:integrations:writedelete_connection:integrations:writelist_credentials:integrations:readcreate_credential:integrations:writeupdate_credential:integrations:writedelete_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: permisoscrm:readysubscribers:read; devuelve la vinculación,revision, candidatos,truncatedy unevidence_tokende corta duración.confirm_ozma_chat_binding: permisoscrm:write,crm:read,subscribers:readysubscribers:write; también recibe elcontact_idelegido,expected_revisiony elevidence_tokensin 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: permisoscrm:writeysubscribers:write; pasaexpected_revisionde 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íabot_id,subjectynavigation_origins, y opcionalmentequiet_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íabot_id,subscription_id,content_document_id,content_version, elpayloadde la notificación y la confirmación obligatoriaconfirm: 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 permisoweb_push.writey las comprobaciones 2FA aplicables. La respuesta contienemessage_idystatus: "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íabot_idy los campos que quieras cambiar:subject,navigation_origins,quiet_hoursy/oenabled. 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. Indicabot_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.
- Envía
bot_idsinconfirmo conconfirm: false. La respuesta incluye el número de suscripciones activas enactive_subscriptionsyconfirmation_required: true. La vista previa mantiene las claves y suscripciones y no consume el límite de rotación. - Envía el mismo
bot_idconconfirm: truecuando aceptes que todas las suscripciones activas caduquen y que los navegadores afectados tengan que suscribirse de nuevo. Para confirmar también hace falta el permisointegrations.secretsdel 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 incluyeconfigsin la clave privada y el número real de suscripciones caducadas enexpired_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íabot_idy, opcionalmente,limit(1–100, 50 por defecto) y elcursorde la respuesta anterior. Devuelve los archivos de la biblioteca,in_useynext_cursor; excluye los adjuntos de chats y correos.delete_media_asset(media:write). Envíabot_id,asset_idyconfirm: true. Requiere el permiso de reacciones (reactions) y la funciónimage_storagedel plan. Si el archivo está en uso, incluida la base de conocimiento, devuelvemedia_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:writeget_media:media:writedownload_media:media:write; descarga el archivo codificado en base64 ({mime, size_bytes, data_base64}), por ejemplo para subirlo a otro bot conupload_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:readdelete_template:templates:writecreate_template_from_bot:templates:writeapply_template:templates:write
Suscriptores, chats y diálogos (subscribers)
list_subscribers:subscribers:read; paginaciónoffset/limit, búsqueda, filtros por etiquetas yis_blocked=true|false. Cada registro incluyeis_blockedyblocked_atsi la persona bloqueó el bot.list_chats:subscribers:readlist_dialogs:subscribers:read; conversaciones de la bandeja del operador con suscriptor, plataforma, vista previa del último mensaje y última actividad; paginación porcursor/next_cursor.read_dialog:subscribers:read; mensajes de una conversación, con páginas anteriores mediantebefore_id. Elmetade audio o vídeo transcrito contienetranscript_status,transcriptytranscript_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 detextdebe contener texto.delete_dialog_message:subscribers:write; Elimina el mensaje. Incluyeconfirm=truepara 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 exigeIdempotency-Key, yPOST /api/bots/{botID}/users/{userID}/dialog/reactionscon{"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_countytags(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 elsubscriber_idcanónico.update_support_dialog_meta·support:write·bot_id,subscriber_id,expected_revisiony al menos un cambio:status,snoozed_until,assignee_id,group_idoassign_to_self. Los campos omitidos no cambian. La respuesta contiene el estado actualizado con la nuevarevision.
Reglas de cambio:
statusadmiteopen,pending,closedosnoozed.openreabre un diálogo cerrado. Desdeclosedsolo se puede pasar aopenosnoozed. No se puede enviar el estado actual sin ningún otro cambio.- Para pasar a
snoozed, indica ensnoozed_untilun momento futuro en formato RFC 3339.snoozed_untilsolo se acepta si el diálogo queda en el estadosnoozed. assignee_idadmite el ID de un miembro de este bot. Una cadena vacía quita la asignación.assign_to_self: trueasigna el diálogo al titular del token y no se puede combinar conassignee_id.group_idadmite 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 arraynotes. Cada nota tieneid,bot_id,subscriber_id,author_id,body,created_atyedited_atsi 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 estableceedited_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 arraytags: el vocabulario de etiquetas del bot ordenado porname. Cada etiqueta tieneidyname, y tambiéncolorsi se definió un color.create_support_dialog_tag·support:write·bot_id,namey, opcionalmente,color. Se quitan los espacios al principio y al final dename; no se admite un nombre vacío ni de más de 100 caracteres.colores una cadena de hasta 32 caracteres para la visualización, por ejemplo#ff8800; el servidor no comprueba su formato. Devuelve la etiqueta conid,nameycolor.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_tagyremove_support_dialog_tagcon la mismaexpected_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 devuelvedialog revision conflict. Vuelve a leer el diálogo conget_support_dialog_meta, compruebatagsy usa elsubscriber_idcanónico y larevisionque devuelve. - Repetir
create_support_dialog_tagcon el mismonameno crea una copia y devuelve la etiqueta con suidexistente. Sin el campocolor, el color actual se conserva, así que repetir es seguro. Uncolorexplícito sustituye el color, y una cadena vacía""lo borra. - Repetir
delete_support_dialog_tagdevuelvedialog tag not found. La eliminación no se puede deshacer: una etiqueta creada de nuevo con el mismo nombre recibe unidnuevo 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 arrayitems: 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 porshortcutalfabéticamente. Cada plantilla tieneid,shortcut,title,blocksyusage_count; una personal también tieneowner_id.create_quick_reply·support:write·bot_id,shortcuty, opcionalmente,title,blocksypersonal. Enshortcut, envía el atajo sin/; no se admite un valor vacío.blocksson 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: truecrea 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: incrementausage_counten 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_replyconpersonal: truey el mismoshortcutno crea una copia. Sustituyetitleyblocksde la plantilla personal existente y conserva suidy suusage_count. - Repetir
create_quick_replypara una plantilla compartida crea otra plantilla con el mismoshortcuty unidnuevo. Si se perdió la respuesta de la creación, consulta primerolist_quick_replies. - Cada llamada a
use_quick_replyvuelve a incrementar el contador en 1. Llámala una vez por cada inserción de la plantilla. - Repetir
delete_quick_replypara una plantilla ya eliminada devuelvequick 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 arraygroupsordenado porname. Cada grupo tieneid,name,strategyymember_ids: los ID de las cuentas de sus miembros o un array vacío. El orden demember_idsen la lista no está garantizado.create_operator_group·support:write·bot_id,nameystrategyopcional. Se recortan los espacios al principio y al final dename. Un nombre vacío devuelvename is required, y uno de más de 200 caracteres,name must be at most 200 characters. El nombre es único dentro del bot.strategyadmiteleast_busy(predeterminado),round_robinoall; cualquier otro valor devuelvestrategy must be least_busy, round_robin or all. Devuelvegroupycreated.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. Devuelvegroupychanged.remove_operator_group_member·support:write·bot_id,group_id,owner_id. Quita la cuenta del grupo. Devuelvegroupychanged.
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_groupcon los mismosnameystrategyno crea una copia y devuelve el grupo existente concreated: false. Sinstrategyse usaleast_busy. El mismo nombre con otra estrategia devuelvean 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 compruebalist_operator_groupsantes de repetir. - Repetir
add_operator_group_memberoremove_operator_group_memberes seguro: si la cuenta ya está en el grupo o ya se quitó, nada cambia y se devuelve elgroupactual conchanged: false. - Repetir
delete_operator_groupdevuelveoperator group not found. operator group change conflicted with a concurrent update; retrysignifica que no se escribió nada y puedes repetir la misma llamada. Trasoperator group could not be changed, comprueba el estado conlist_operator_groupsantes de repetir.account processing is suspendedsignifica 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 arrayrules: todas las reglas del bot, activadas y desactivadas, en orden de evaluación. Las reglas se ordenan porpriorityy, con igual prioridad, porname.create_routing_rule·support:write·bot_id,name, exactamente uno degroup_idyassignee_id, ypriority,enabledymatchopcionales. Cada llamada crea una regla nueva. Devuelverule.update_routing_rule·support:write·bot_id,rule_idy al menos uno dename,priority,enabled,match,group_idoassignee_id. Sin cambios, el servidor devuelvenothing to update. Devuelve laruleactualizada.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 arrayrulesen 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,igofb. Basta con una coincidencia. Los valores se pasan a minúsculas; cualquier otro valor devuelvematch.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 delist_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 ywarningsincluye 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_rulecrea otra regla con unidnuevo, aunque los campos sean iguales. Si se perdió la respuesta de una creación, comprueba primerolist_routing_rules. - Repetir
update_routing_rulevuelve 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 enlist_routing_rules. - Repetir
delete_routing_ruledevuelverouting rule not found. La eliminación es irreversible: una regla creada de nuevo recibe unidnuevo. - Tras un
reorder_routing_rulescorrecto, repetirlo con los mismosexpected_rule_idssuele devolverrouting 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 leerlist_routing_rules, comprueba el orden y solo entonces repite con los nuevosexpected_rule_ids. - Tras
routing rule could not be changed, comprueba el estado conlist_routing_rulesantes de repetir.account processing is suspendedsignifica 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 tieneuser_idyunread, además dechannel_id,scope_channel_idysubscriber_idcuando 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_idysubscriber_idopcionales. Devuelve el estado de lectura de un diálogo sin cambiar nada.mark_dialog_read·support:write·bot_id,user_id,channel_id,subscriber_idylast_read_message_idopcionales. 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 enfromy las transiciones hastatosegú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 entransitions, conat,stateyreason.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 ejemploEurope/Belgrade, y todos los intervalos semanales. Usaweekday(0 para domingo y 6 para sábado),start_minuteyend_minuteen minutos desde la medianoche local. El campo opcionaloverflow_group_ididentifica 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 usalocal_date(YYYY-MM-DD),kind(closedocustom),nameeintervals. Usa intervalos vacíos paraclosede indicastart_minuteyend_minuteen cada intervalo decustom. Pasaholidays: []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 horarioworkingonon_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:readget_stats_summary:stats:readget_stats_recent:stats:readget_stats_log:stats:readget_reaction_health:stats:readget_analytics:stats:readget_analytics_chats:stats:readget_site_widget_analytics:stats:readget_site_popup_analytics:stats:readget_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 unimpression_idvá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:readget_experiment:experiments:readget_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:readlist_tariffs:billing:readget_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/flowymybot://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ón | Herramientas | Permisos |
|---|---|---|
| Managed AI | invoke_managed_ai, get_managed_ai_usage | managed_ai:invoke, managed_ai:usage:read |
| Copilot | create_copilot_proposal, get_copilot_proposal, validate_copilot_proposal, simulate_copilot_proposal, apply_copilot_proposal, reject_copilot_proposal | copilot:use y permisos de lectura y edición de recorridos |
| Flow Intelligence | get_flow_intelligence_policy y herramientas de vista previa, actualización y recálculo | analytics:read, journey:edit |
| Replay | list_execution_traces, get_execution_trace, simulate_execution_trace, capture_regression_fixture, list_regression_fixtures, get_regression_fixture, run_regression_fixture, list_replay_runs | journey:read/edit |
| Playbooks | list_vertical_playbooks y herramientas de preparación, comprobación, instalación y actualización; los KPI siguen disponibles solo por REST | permisos de lectura y escritura de plantillas, bots y reacciones |
| Onboarding | start_outcome_onboarding, update_outcome_onboarding, complete_outcome_onboarding | permisos de bots, plantillas y reacciones |
| Meta | list_meta_connections, start_meta_authorization, refresh_meta_assets y herramientas para comprobar, elegir, conectar y desconectar activos | permisos 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
- Herramientas preparadas para agentes de IA: integraciones de GetMyBot para Claude Code y otros agentes.
- Autorización y tokens: crear un PAT para MCP.
- Inicio rápido de la API: alternativa REST.
- Referencia interactiva: todos los endpoints REST.
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_idcreate_tracking_rule:bot_id,name,event_name,trigger_kind,selector,page_patterns,extractions,enabledupdate_tracking_rule:bot_id,rule_id,expected_revision;name,event_name,trigger_kind,selector,page_patterns,extractions,enableddelete_tracking_rule:bot_id,rule_id,expected_revision