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 reciberedirect_urlpara 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, responde503. Bitrix24 responde503por 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): responde409con 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. Responde503si 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=trueincluye 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 serPOST.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 conlimitycursor.
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.
- Embudos de eventos guardados: reglas y consultas de cohortes.
- Experimentos y atribución: versiones, eventos e ingresos.
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,PATCHyDELETEautenticados, pero no las lecturas porGET.
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,balancedyquality; proveedor:auto,openai,anthropicodeepseek.Idempotency-Keyes 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/catalogde 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/sessionyPOST /api/onboarding/session/complete. - Messenger e Instagram:
/api/meta/connectionsdevuelve 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
- Referencia de la API: endpoints y ejemplos interactivos.
- Configuración, equipo y acceso: tokens de API de un bot.
- Colecciones y datos: datos disponibles mediante la API.
- Solicitudes web y webhooks: integración en ambas direcciones.