Base de conocimiento de GetMyBot

API REST y tokens

Cómo gestionar bots desde un programa: tipos de tokens, operaciones REST y enlaces a ejemplos de solicitudes.

En esta página

La API REST permite que tu programa se comunique con GetMyBot por HTTP para, por ejemplo, leer solicitudes de una colección, crear reacciones o consultar estadísticas. Si solo configuras el bot desde el panel, no necesitas la API. Para integrar un programa, empieza con la primera solicitud y consulta los campos exactos en la referencia interactiva.

El acceso se concede mediante un token, una clave secreta para el programa. Hay tokens de un bot concreto y tokens personales para automatizar tareas dentro de una cuenta. Tienen capacidades diferentes.

Tokens de API de un bot

Se crean en Configuración → Tokens de API. Cada token está vinculado a un bot y permite llamar a sus endpoints REST de reacciones, usuarios, colecciones, estadísticas y otras funciones. El valor se muestra una sola vez al crearlo: guárdalo en un lugar seguro. La lista muestra el nombre, una versión oculta del valor y la fecha de creación. Elimina los tokens que ya no necesites.

Tokens de acceso personal (PAT)

Los tokens personales (PAT) empiezan por mbp_ y sirven para automatizaciones e integraciones de la cuenta. Se crean en la cuenta personal y se envían mediante Authorization: Bearer mbp_…. Cada token tiene permisos (scopes) de la forma recurso:acción, por ejemplo reactions:read o bots:write. * representa todos los permisos públicos. Puedes limitar su vigencia y se almacenan como hashes. Así das acceso limitado a un programa sin compartir tu contraseña.

Qué permite hacer la API

La API expone las entidades del panel: bots y configuración, reacciones (también su importación y exportación), suscriptores y etiquetas, colecciones y registros, estadísticas y registro de solicitudes, y difusiones. Puedes usarla para crear paneles propios, sincronizaciones y automatizaciones.

Canales y WhatsApp

También puedes gestionar por REST los canales Telegram, WhatsApp y VK. Leer canales y plantillas de WhatsApp requiere bots:read; modificarlos requiere bots:write. No hay un permiso separado solo para canales.

  • GET /api/channels/capabilities (bots:read): matriz de capacidades de los canales; una sesión web puede leerla sin scope.
  • GET /api/bots/{botID}/channels (bots:read): canales del bot.
  • POST /api/bots/{botID}/channels (bots:write): conectar WhatsApp o VK.
  • DELETE /api/bots/{botID}/channels/{channelID} (bots:write): desconectar un canal.
  • GET /api/bots/{botID}/channels/{channelID}/templates (bots:read): plantillas de WhatsApp del canal.
  • POST /api/bots/{botID}/channels/{channelID}/templates (bots:write): crear una plantilla y enviarla a revisión de Meta.
  • POST /api/bots/{botID}/channels/{channelID}/templates/sync (bots:write): sincronizar las plantillas desde Meta.
  • PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): modificar una plantilla.
  • DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): eliminar una plantilla.
  • POST /api/bots/{botID}/channels/{channelID}/templates/media (bots:write): subir un archivo de ejemplo para la cabecera, sea imagen, vídeo o documento.

La referencia de la API contiene esquemas, parámetros y ejemplos. La guía de WhatsApp explica el canal y sus plantillas.

Conexiones CRM

CRM tiene permisos propios, crm:read y crm:write. integrations:* no los sustituye. Cada ruta comprueba también el derecho Reacciones del bot.

La conexión depende del proveedor:

  • POST /api/bots/{botID}/crm/connections/amocrm/start (crm:write): envía {"account_key": "acme.amocrm.ru"} y recibe redirect_url para abrirlo en el navegador. Se permiten como máximo tres inicios por minuto y cuenta. Si la aplicación OAuth de amoCRM no está configurada en la plataforma, responde 503. Bitrix24 responde 503 por el mismo motivo.
  • GET /api/integrations/crm/{provider}/callback: destino de la redirección del navegador. No necesita token: usa el estado de un solo uso, válido durante cinco minutos, emitido al iniciar la conexión. Devuelve un resumen seguro, nunca credenciales.
  • POST /api/bots/{botID}/crm/connections/retailcrm (crm:write): conectar mediante clave de API.
  • POST /api/bots/{botID}/crm/connections/ozmacrm (crm:write): conectar con credenciales OIDC, inicio de sesión y configuración de entidades.

Hay además rutas para descubrir campos y embudos, revisar versiones del mapeo, obtener una vista previa, iniciar y repetir sincronizaciones, consultar operaciones y tareas y resolver conflictos. DELETE /api/bots/{botID}/crm/connections/{connectionID} desconecta CRM. Otras tres operaciones por suscriptor (estado CRM, sincronización manual y exportación de la conversación) están bajo /api/bots/{botID}/subscribers/{subscriberID}/crm/…, con subscribers:* y el derecho Diálogos.

Seis herramientas MCP permiten consultar CRM sin modificarlo: consulta MCP. La tabla completa de rutas y el comportamiento de cada proveedor están en Integraciones CRM.

Contenido, campañas de correo y ventanas emergentes

Estas funciones tienen permisos propios y sus endpoints comprueban además el derecho Reacciones del bot. Un token no puede acceder a datos fuera de su cuenta.

  • content:read / content:write: documentos y plantillas de contenido: GET|POST /api/bots/{botID}/content, GET /api/bots/{botID}/content/{documentID}, PATCH /api/bots/{botID}/content/{documentID}/draft, POST /api/bots/{botID}/content/{documentID}/publish|clone|archive|test-send, POST /api/bots/{botID}/content/{documentID}/validate|preview, GET /api/bots/{botID}/content/test-recipients, GET|POST /api/bots/{botID}/content-templates, DELETE /api/bots/{botID}/content-templates/{templateID}.
  • email_campaigns:read / email_campaigns:write: campañas e informes: GET|POST /api/bots/{botID}/email-campaigns, GET|PATCH /api/bots/{botID}/email-campaigns/{campaignID}, GET /api/bots/{botID}/email-campaigns/{campaignID}/report|recipients|links, POST /api/bots/{botID}/email-campaigns/{campaignID}/consent-preview, POST /api/bots/{botID}/email-campaigns/{campaignID}/test-send|schedule|clone|pause|resume|cancel|archive.
  • popups:read / popups:write: GET|POST /api/bots/{botID}/popups, PATCH|DELETE /api/bots/{botID}/popups/{popupID}, GET /api/bots/{botID}/popups/{popupID}/stats|experiment, POST /api/bots/{botID}/popups/preflight.
  • settings:read / settings:write: dominios de envío y rutas de correo entrante bajo /api/bots/{botID}/email/…. El dominio de envío es una configuración del bot y usa estos permisos, sin uno específico. La lectura requiere acceso al bot; crear, comprobar y eliminar requiere también Reacciones.

consent-preview, validate y preview usan POST aunque no cambien datos. Por eso se registran en la auditoría como cualquier otro POST autenticado.

Las modificaciones usan control de versiones: envía el expected_revision que acabas de leer. Si recibes 409, vuelve a cargar los datos antes de reintentar; no es un fallo de transporte. POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule exige además "confirm": true. Si los destinatarios no pasan la comprobación, devuelve 422 con el resultado completo.

Los endpoints públicos de seguimiento, baja y webhooks del proveedor (/e/t/…, /u/…, /esp/{provider}/webhook y /esp/{provider}/inbound) no forman parte de la API con token. Se explican en Campañas de correo.

Notificaciones del navegador y SDK de cliente

Ambas funciones tienen permisos propios y comprueban derechos del bot: Analítica para leer y Reacciones para modificar. Todos los cambios se auditan.

Notificaciones del navegador: web_push:read / web_push:write:

  • GET /api/bots/{botID}/web-push (web_push:read): configuración sin secretos, con clave pública VAPID, contacto, orígenes permitidos para navegar y horas de silencio. Nunca devuelve la clave privada.
  • GET /api/bots/{botID}/web-push/subscriptions (web_push:read): suscripciones recientes, estado del consentimiento, familia del navegador, idioma y zona horaria. Nunca devuelve la dirección del servicio push ni las claves de cifrado.
  • GET /api/bots/{botID}/web-push/report (web_push:read): recuentos de suscripciones y recibos.
  • POST /api/bots/{botID}/web-push/enable (web_push:write): crea las claves VAPID la primera vez; después actualiza la configuración de forma idempotente.
  • PATCH /api/bots/{botID}/web-push (web_push:write): contacto, orígenes de navegación, horas de silencio y estado de activación.
  • POST /api/bots/{botID}/web-push/rotate-keys (web_push:write): responde 409 con el número de suscripciones activas hasta que envíes "confirm": true. La confirmación invalida todas las suscripciones existentes.
  • POST /api/bots/{botID}/web-push/test (web_push:write): envía un mensaje de prueba a una suscripción usando un documento Push publicado. Los envíos normales se hacen mediante difusiones y campañas.

SDK de cliente: customer_sdk:read / customer_sdk:write:

  • GET /api/bots/{botID}/customer-sdk (customer_sdk:read): configuración sin secretos: clave del proyecto, región, aplicaciones permitidas, versión del secreto de identidad y, durante una rotación, fecha de caducidad del secreto anterior.
  • GET /api/bots/{botID}/customer-sdk/installations (customer_sdk:read): hasta 200 instalaciones recientes.
  • GET /api/bots/{botID}/customer-sdk/report (customer_sdk:read): recuentos de instalaciones y tokens push.
  • POST /api/bots/{botID}/customer-sdk/enable (customer_sdk:write): crea el proyecto y devuelve el secreto de identidad una sola vez; después actualiza la configuración de forma idempotente. Responde 503 si falta el secreto de firma de claves de proyecto en la instalación.
  • PATCH /api/bots/{botID}/customer-sdk (customer_sdk:write): aplicaciones permitidas y estado de activación.
  • POST /api/bots/{botID}/customer-sdk/rotate-secret (customer_sdk:write): devuelve un secreto nuevo y mantiene el anterior válido 24 horas más.
  • DELETE /api/bots/{botID}/customer-sdk/installations/{installationID} (customer_sdk:write): revoca un dispositivo.

Las rutas para dispositivos del SDK, /sdk/v1/*, no forman parte de esta API. Usan un token de instalación y una época de identidad; no aceptan PAT, del mismo modo que /api/* no acepta tokens de instalación. El servidor publica su esquema OpenAPI separado sin autenticación en GET /sdk/openapi.yaml.

Difusiones

Las difusiones tienen un único permiso: broadcasts:write. No existe una pareja read/write como en otras funciones ni un permiso broadcasts:read, así que también se necesita broadcasts:write para leer listas, informes y destinatarios. No puedes crear un token de solo lectura para difusiones. Todas las rutas comprueban además el derecho Reacciones del bot.

Las difusiones de segunda generación combinan contenido, público y canales:

  • GET /api/bots/{botID}/broadcasts: lista; ?archived=true incluye las archivadas.
  • POST /api/bots/{botID}/broadcasts: crea un borrador.
  • PATCH /api/bots/{botID}/broadcasts/{broadcastID}: modifica un borrador.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight: comprueba los destinatarios; no envía nada, pero se audita por ser POST.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule: inicia la difusión.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send: prueba con un contacto verificado.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/archive: archiva.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/report: informe por canal.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients: destinatarios con limit y cursor.

Las difusiones antiguas basadas en reacciones siguen disponibles bajo la misma ruta base. Se inician mediante POST /api/bots/{botID}/reactions/{reactionID}/broadcast con un cuerpo como {"paid": false, "labels": ["vip"]}. Solo estas difusiones pueden limitarse por etiquetas. Ambas generaciones comparten cuatro rutas:

  • GET /api/bots/{botID}/broadcasts/{broadcastID};
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel.

El servidor busca primero una difusión de segunda generación y después una antigua. Por eso el cuerpo y la respuesta dependen del tipo al que pertenezca el ID. La difusión nueva exige {"expected_revision": N} y devuelve el objeto completo. La antigua ignora el cuerpo y responde {"status": "pausing"}, {"status": "resuming"} o {"status": "canceled"}.

Los cuerpos se validan estrictamente: un campo desconocido produce 400. Para modificar, envía el expected_revision leído; 409 indica que debes recargar antes de reintentar. schedule exige además "confirm": true; sin ello devuelve 400.

En difusiones, los códigos siguientes significan:

  • 402: el plan del propietario no incluye difusiones;
  • 403: las difusiones de pago no están activadas para el bot;
  • 409: revisión antigua o difusión no lista, por ejemplo contenido sin publicar, segmento sin recalcular, experimento detenido o público vacío;
  • 422: falta contenido o no pasa la validación de algún canal;
  • 429: demasiados envíos de prueba.

En MCP, broadcasts:write cubre start_broadcast, get_broadcast, pause_broadcast, resume_broadcast, cancel_broadcast, list_content_broadcasts y get_content_broadcast_report. Los dos últimos y get_broadcast solo leen, pero requieren ese mismo permiso. Crear, editar, comprobar destinatarios, iniciar, probar y archivar difusiones de segunda generación solo es posible por REST. pause_broadcast, resume_broadcast y cancel_broadcast en MCP solo actúan sobre difusiones antiguas basadas en reacciones. Consulta la guía de Difusiones.

Acceso móvil

La aplicación móvil usa sus propios tokens de acceso y actualización y muestra un panel conjunto de bots. Se comunica con el mismo backend.

Referencia de la API

La referencia interactiva enumera los endpoints públicos disponibles mediante PAT, sus parámetros, esquemas, permisos y ejemplos de curl, JavaScript y Python. Puedes probar solicitudes desde esa página con tu token.

Embudos y experimentos

Las definiciones e informes de embudos guardados usan analytics:read y analytics:write. Guardar una cohorte como segmento requiere además segments:write. Los experimentos, sus cambios de estado, informes y cohortes usan experiments:read y experiments:write. Todas estas rutas comprueban el derecho Analítica del bot.

La auditoría depende del método HTTP: se registran los POST, PUT, PATCH y DELETE de un propietario autenticado, incluso las consultas de informes o cohortes que no cambian datos pero usan POST. Las lecturas y listas por GET no se registran como acciones.

Para informes envía siempre un intervalo UTC RFC3339 acotado. Los informes de embudos y experimentos abarcan como máximo 366 días. El ingreso de un experimento tiene un entero minor y una moneda ISO 4217 currency; no sumes monedas distintas en el cliente.

curl "$BASE_URL/api/bots/$BOT_ID/funnels?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $PAT"

Devuelve sin cambios el cursor next recibido del servidor. Un cursor o cuerpo incorrecto devuelve 400. Un recurso no disponible en el bot, o una versión de experimento solicitada expresamente que no existe, devuelve 404. Una revisión antigua o un conflicto al elegir ganador devuelve 409. Consulta los cuerpos completos en la referencia y las guías de Embudos y Experimentos.

Seguridad

  • Los tokens se muestran una sola vez; trátalos como secretos.
  • Los secretos de bots y credenciales se almacenan cifrados.
  • La auditoría registra los POST, PUT, PATCH y DELETE autenticados, pero no las lecturas por GET.

Customer AI, análisis de escenarios, playbooks y Meta

Las siguientes funciones ayudan a automatizar tareas con IA. Sus nombres en la API permanecen en inglés; aquí se explica para qué sirve cada una:

  • Managed AI: POST /api/v1/ai/responses (managed_ai:invoke) consulta a la IA; GET /api/v1/ai/usage (managed_ai:usage:read) muestra el consumo. Perfiles: fast, balanced y quality; proveedor: auto, openai, anthropic o deepseek. Idempotency-Key es obligatorio al invocar. Usar tu propia clave del proveedor no cambia automáticamente a Managed AI de pago.
  • Copilot: crea una propuesta de modificación de reacción en /api/reactions/{rootID}/copilot/proposals. En /api/copilot/proposals/{proposalID} puedes consultarla, validarla, simularla, aplicarla o rechazarla. Aplicarla crea un borrador; no lo publica.
  • Flow Intelligence: muestra datos del recorrido por una reacción, ejemplos de ejecuciones y reglas de análisis. Las opciones y el recálculo para un período acotado están en /api/bots/{botID}/flow-intelligence/*.
  • Explainable Replay: permite leer y simular un registro de ejecución, preparar un ejemplo de prueba sin datos sensibles y comprobar otra ejecución. El agente no puede revelar materiales protegidos.
  • Vertical Playbooks: ofrece el catálogo /api/playbooks/catalog de escenarios preparados, continuar una configuración interrumpida, comprobar su preparación, instalarlos, actualizarlos y consultar indicadores de resultado (KPI).
  • Outcome onboarding: guía la configuración inicial según el objetivo. Usa POST|PATCH /api/onboarding/session y POST /api/onboarding/session/complete.
  • Messenger e Instagram: /api/meta/connections devuelve una dirección para autorizar Meta en el navegador. Después puedes comprobar, elegir y conectar páginas y cuentas de tu panel. Las respuestas no incluyen tokens secretos.

Solo un superadministrador puede gestionar claves de proveedores, enrutamiento, precios y conciliación de cargos. No están disponibles en la API del usuario ni en MCP.

Copilot, Flow Intelligence, Explainable Replay y Vertical Playbooks deben estar activados para tu cuenta. Si la función está desactivada o aún no se ha concedido a tu cuenta, la solicitud se rechazará. MCP aplica la misma restricción.

Qué sigue