Base de conocimiento de GetMyBot

Procesador externo

Ejecuta parte de la lógica del bot en tu servidor mediante WebSocket: conexión, eventos, comandos y respuesta ante una desconexión.

En esta página

Un procesador externo permite ejecutar parte de la lógica del bot en tu servidor. Por ejemplo, tu servidor calcula una oferta personal con los datos de tu empresa y GetMyBot recibe el mensaje del cliente y envía la respuesta preparada a Telegram.

Esta configuración está pensada para desarrolladores. Tu servidor se conecta a GetMyBot mediante una conexión WebSocket persistente, recibe eventos y devuelve comandos con el formato de Telegram Bot API. Las respuestas sencillas y los formularios pueden seguir en el editor visual.

Qué es

Si tu programa debe dirigir la conversación, consultar tu base de datos, calcular algo especial o elegir la siguiente pregunta según reglas complejas, puedes delegarle una reacción concreta. Las demás reacciones siguen funcionando en el editor visual.

Tu programa recibe un evento cuando se activa una regla, llega una respuesta o se pulsa un botón. A continuación indica qué debe hacer el bot. GetMyBot valida los comandos, los pone en cola y los envía con el token del bot. También limita la frecuencia, reintenta los fallos temporales, evita duplicados y guarda los mensajes en el historial del diálogo.

Modelo de funcionamiento

  • GetMyBot acepta la conexión WebSocket. Tu programa se conecta a GetMyBot; no necesita una dirección pública. GetMyBot no llama a tu programa.
  • Autenticación mediante token de integración. El servicio presenta el token al conectarse; GetMyBot lo compara con el hash y mantiene la conexión.
  • Eventos y comandos con formato Telegram Bot API. El programa recibe un evento y responde con una lista de llamadas «método + parámetros», como en un bot de Telegram.
  • GetMyBot ejecuta los comandos con su token. El programa no se conecta directamente con Telegram. GetMyBot valida las llamadas y las coloca en su cola interna de envío (outbox), donde se aplican los límites de frecuencia, reintentos, protección contra duplicados y registro.

Una sola conexión sirve para todos los diálogos de esa integración. El campo session_id identifica cada diálogo.

Configuración de la integración

  1. Abre Integraciones en el menú izquierdo y pulsa Agregar integración.
  2. Selecciona Procesador externo y dale un nombre.
  3. Tras crear la integración, la tarjeta mostrará:
    • URL de conexión: tiene la forma wss://api.mybot.app/ext/ws/<integrationID>, donde <integrationID> es el UUID de la integración. Tu programa se conecta a esta dirección; sin el identificador en la ruta no se establece la conexión.
    • Token: se muestra una sola vez al crear la integración. Guárdalo de forma segura; solo se conserva su hash y no se puede volver a consultar.
    • Regenerar token: crea otro token e invalida el anterior de inmediato. Actualízalo también en tu programa.
    • Indicador En línea: muestra si tu programa mantiene una conexión activa en ese momento.

Parámetros adicionales de la integración que afectan al protocolo:

  • session_ttl_seconds — tiempo de vida de la sesión en segundos (por defecto 3600).
  • on_unavailable_reaction_id — reacción de respaldo que se lanza si el servicio está desconectado en el momento de la activación (ver Fiabilidad).

Vinculación a una reacción

El procesador externo se usa como una acción, no como un disparador independiente. En el editor de reacciones, añade Transferir a manejador externo y selecciona la integración.

El diálogo puede abrirse con cualquier disparador existente de GetMyBot — comando, texto, pulsación de botón, parámetro desde un enlace, solicitud web entrante, programación. Cuando ese disparador se activa y llega a la acción, GetMyBot abre una sesión proxy y envía al servicio el evento session.open.

Si tu programa no está conectado en ese momento, GetMyBot ejecuta la reacción de respaldo configurada en la integración (on_unavailable_reaction_id). Si no hay ninguna, el cliente no recibe respuesta ni mensaje de error.

Conexión y autorización

Endpoint: GET /ext/ws/{integrationID} por WebSocket (wss). integrationID es el UUID de la integración de tipo «Procesador externo». Cada trama puede ocupar como máximo 256 KiB.

Puedes autenticarte de una de estas dos formas.

1. Cabecera al establecer la conexión (recomendado). Envía el token en Authorization:

Authorization: Bearer <token>

2. Trama de autenticación. Si no enviaste la cabecera Bearer, envía esta primera trama durante los 10 segundos posteriores a la conexión:

{ "type": "auth", "token": "<token>" }

Si la trama de autenticación no llega en 10 segundos, la conexión se cierra con el código 4401. Un token incorrecto por cualquiera de los dos métodos también produce el cierre 4401.

El token se genera al crear la integración, se muestra una sola vez y se almacena solo como hash (sha256); la verificación es en tiempo constante. Rotación del token:

POST /api/bots/{botID}/integrations/{integrationID}/rotate-token

El endpoint devuelve el nuevo token en texto plano; el anterior deja de funcionar de inmediato.

Eventos: bot → servicio

Cada evento es una trama JSON (EventEnvelope). El campo type es uno de: session.open, message, callback, session.cancel, session.expired.

Campos del mensaje que contiene el evento:

{
  "type": "session.open",
  "session_id": "string",
  "bot_id": "string",
  "user": {
    "tg_user_id": 123456789,
    "first_name": "Ivan",
    "username": "ivan",
    "params": { "utm": "promo" }
  },
  "chat": { "id": 123456789, "type": "private" },
  "update": { "...": "raw Telegram Update (JSON sin procesar)" },
  "event": { "...": "evento normalizado de GetMyBot (JSON sin procesar)" }
}
  • session_id: identificador de la sesión o diálogo.
  • bot_id: identificador del bot.
  • user: tg_user_id (int64), first_name y username opcionales, y params, un mapa de parámetros del usuario, incluidos los recibidos mediante un enlace.
  • chat: id (int64) y type, por ejemplo "private".
  • update: evento Telegram Update original en JSON. Está presente en session.open, message y callback.
  • event: evento normalizado por GetMyBot en JSON.

El contenido varía según el tipo:

  • session.open: se activó el disparador y empezó un diálogo. Incluye el update original, el event normalizado completo y los user.params.
  • message: llega cuando el servicio espera un mensaje (expect = text/any) y la persona responde. Contiene los mismos datos que session.open.
  • callback: se pulsó un botón enviado antes por el servicio. update contiene el evento original; en user solo está tg_user_id; event contiene únicamente el callback_data que el servicio puso en el botón:
{ "callback_data": "<valor original definido por el servicio en el botón>" }
  • session.cancel / session.expired: solo incluyen session_id, bot_id, user.tg_user_id y chat.id (en cancel, también chat.type). No incluyen update ni event. Solo se entregan si el servicio está conectado; no entran en la cola de eventos pendientes.

Comandos: servicio → bot

Un comando es una trama JSON (CommandEnvelope). El campo type es uno de: execute, session.close, auth, ping, pong.

{
  "type": "execute",
  "session_id": "string",
  "methods": [
    { "method": "sendMessage", "params": { "text": "Hola" } }
  ],
  "expect": "none"
}
  • session_id: diálogo al que pertenece el comando.
  • token: solo para type: "auth" (consulta Conexión y autorización).
  • methods: lista de objetos { "method": "<método de Telegram Bot API>", "params": { ... } }. Usa el nombre exacto del método, por ejemplo sendMessage, y sus parámetros.
  • expect: indica si el servicio espera otra respuesta: "none", "text" o "any". Un valor vacío equivale a none.
  • session.close: cierra expresamente el diálogo.

GetMyBot valida los comandos y los pone en su cola de envío (outbox). Desde allí se envían a Telegram con el token del bot, límites de frecuencia, reintentos, protección contra duplicados y registro.

Cómo se procesa execute

El comando execute se ignora por completo si session_id está vacío o si la sesión no existe, está cerrada, ha caducado o pertenece a otra integración.

Después:

  • Frecuencia: hasta 60 comandos execute por minuto y sesión, medidos en una ventana móvil. Los que excedan el límite se ignoran.
  • Hasta 30 métodos en un solo execute; los sobrantes se descartan silenciosamente.
  • Cada método se compara con la lista de métodos permitidos. Los demás se rechazan.
  • Protección del chat: si chat_id o from_chat_id dentro de params contiene un valor distinto de 0 y del chat de la sesión, se rechaza ese método. Puedes omitir chat_id: GetMyBot añadirá el del diálogo actual.
  • Botones inline con callback_data se tokenizan automáticamente (formato interno x:<token>); el tiempo de vida del botón es hasta que expire la sesión. Los botones url/webapp/switch_inline no se modifican.

Métodos permitidos

El servicio solo puede enviar y gestionar mensajes del diálogo actual mediante los métodos de esta lista. Los demás se ignoran sin enviar un error.

  • envío: sendMessage, sendPhoto, sendDocument, sendVideo, sendAudio, sendMediaGroup, sendAnimation, sendVoice, sendLocation, sendChatAction;
  • edición y eliminación: editMessageText, editMessageCaption, editMessageReplyMarkup, deleteMessage;
  • respuesta a pulsación: answerCallbackQuery;
  • reenvío y copia: forwardMessage, copyMessage;
  • fijación: pinChatMessage, unpinChatMessage.

Los métodos a nivel de cuenta (setWebhook, getUpdates, logOut, close, setMyCommands, etc.) no están permitidos.

Espera y ciclo de vida de la sesión

Después de cada execute, la sesión permanece abierta o se cierra según expect y los botones inline con callback_data:

  • expect = text o any: el siguiente mensaje del usuario llega al servicio como evento message.
  • expect = none y sin botones de callback: la sesión se cierra automáticamente. El mensaje es el último de ese diálogo.
  • expect = none pero con botones de callback: la sesión sigue abierta para recibir sus pulsaciones hasta que caduquen los tokens de los botones (al finalizar el TTL).

expect solo controla la espera de mensajes, no la de botones. Un botón tokenizado sigue enviando pulsaciones mientras estén vigentes la sesión y su token, sea cual sea el valor de expect.

El diálogo queda bajo el control del servicio mientras la sesión esté abierta:

  • Mensaje mientras se espera una respuesta (expect = text/any): llega al servicio como message sin activar las reacciones normales del bot.
  • Pulsación de un botón tokenizado: llega como callback con el callback_data original. GetMyBot confirma la pulsación con answerCallbackQuery y verifica el bot, usuario y chat de la sesión. Pulsar el botón no cierra la sesión.
  • /cancel (también /cancel@bot y la palabra rusa отмена) con una sesión externa activa: se cierra la sesión, se envía session.cancel al servicio y el usuario recibe Отменено.. La palabra española «cancelar» no es un comando integrado.
  • Un diálogo por usuario: una sesión nueva sustituye a la anterior y se envía session.cancel para la sesión desplazada.
  • Fin del TTL: la sesión pasa a expired y se envía session.expired si el servicio está conectado.

Límites y tiempos de espera

  • Tamaño de trama: 256 KiB.
  • TTL de sesión: por defecto 3600 segundos (configurable con el parámetro session_ttl_seconds de la integración).
  • Frecuencia de comandos: 60 execute por minuto por sesión (ventana deslizante).
  • Métodos en un solo execute: hasta 30 (los sobrantes se descartan).
  • Sesiones abiertas por integración: hasta 1000.
  • Cola offline: hasta 100 eventos por sesión.
  • Heartbeat: ping cada 30 segundos; tiempo de espera por inactividad — 60 segundos.
  • Tiempo de espera de la trama de autenticación: 10 segundos.

Fiabilidad (heartbeat, offline, cola, fallback)

El heartbeat comprueba periódicamente que la conexión siga activa. El fallback es una reacción de respaldo para cuando tu programa no esté disponible. Configúrala de antemano, por ejemplo, para avisar al cliente de la demora y ofrecerle hablar con un operador.

  • Comprobación de conexión. GetMyBot envía {"type":"ping"} cada 30 segundos y cierra la conexión si el cliente permanece inactivo más de 60 segundos. Tu programa también puede enviar ping o pong. Perder la conexión no cierra los diálogos: las sesiones permanecen en la base de datos hasta que termine su TTL.
  • Reconexión. Tu programa debe volver a conectarse si se corta la conexión. Las sesiones abiertas sobreviven a los reinicios hasta que termine su TTL.
  • Servicio desconectado al comenzar. GetMyBot ejecuta la reacción de respaldo (on_unavailable_reaction_id). Si no hay ninguna configurada, no envía respuesta.
  • Cola durante la desconexión. Los eventos message y callback pendientes se guardan en orden de llegada (FIFO), hasta 100 por sesión y solo hasta que expire la sesión. Se envían al reconectar. session.open, session.cancel y session.expired no se guardan en esta cola.
  • Entrega como máximo una vez (at-most-once). Si la cola se llena o caduca, algunos eventos se pierden. Diseña tu programa para poder continuar el diálogo después de un evento perdido.

Indicador de estado online

Para saber si tu programa está conectado, consulta:

GET /api/bots/{botID}/integrations/{integrationID}/status

Respuesta:

{ "online": true }

El mismo indicador aparece en la tarjeta de la integración. En MCP puedes usar get_integration_status.

Seguridad

GetMyBot envía los comandos de tu programa con el token del bot. Por eso limita lo que ese programa puede hacer:

  • Sin solicitudes salientes al programa. GetMyBot es el servidor WebSocket; tu programa se conecta a él. La plataforma no visita una URL aportada por el programa, lo que evita esa vía de SSRF.
  • Token protegido. Se guarda solo su hash sha256, se compara en tiempo constante y se puede regenerar.
  • Aislamiento. Cada comando pertenece a su integración y cada sesión a un bot, usuario y chat. Tu conexión no recibe eventos de otros bots.
  • Métodos y chat restringidos. La lista permitida y el chat_id del diálogo impiden enviar mensajes a chats arbitrarios.
  • Token del bot privado. Tu programa no recibe el token del bot ni se conecta directamente a Telegram.
  • Secretos ocultos. El token de la integración y los valores sensibles se ocultan en el historial y los logs.

Ejemplos

Este procesador mínimo envía un mensaje al abrir el diálogo y cierra la sesión (expect: "none"). Indica el ID de integración y su token mediante variables de entorno. La dirección debe incluir <integrationID> en la ruta.

Node.js

import WebSocket from "ws";

const URL = `wss://api.mybot.app/ext/ws/${process.env.MYBOT_INTEGRATION_ID}`;
const ws = new WebSocket(URL, {
  headers: { Authorization: `Bearer ${process.env.MYBOT_TOKEN}` },
});

ws.on("message", (raw) => {
  const ev = JSON.parse(raw);
  if (ev.type === "session.open") {
    ws.send(JSON.stringify({
      type: "execute",
      session_id: ev.session_id,
      expect: "none",
      methods: [{ method: "sendMessage", params: { text: "¡Hola desde el procesador externo!" } }],
    }));
  }
});

Python

import json, os, asyncio, websockets

async def main():
    url = f"wss://api.mybot.app/ext/ws/{os.environ['MYBOT_INTEGRATION_ID']}"
    headers = {"Authorization": f"Bearer {os.environ['MYBOT_TOKEN']}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        async for raw in ws:
            ev = json.loads(raw)
            if ev["type"] == "session.open":
                await ws.send(json.dumps({
                    "type": "execute",
                    "session_id": ev["session_id"],
                    "expect": "none",
                    "methods": [
                        {"method": "sendMessage", "params": {"text": "¡Hola desde el procesador externo!"}}
                    ],
                }))

asyncio.run(main())

Botón inline y manejo de callback

Para capturar una pulsación, envía un botón con callback_data (GetMyBot lo tokeniza automáticamente). Con expect: "none" y un botón, la sesión permanece abierta mientras viva el token del botón — la pulsación llegará como evento callback en el que event.callback_data es igual al valor original. No es necesario confirmar la pulsación (answerCallbackQuery) — GetMyBot lo hace por su cuenta.

if (ev.type === "session.open") {
  ws.send(JSON.stringify({
    type: "execute",
    session_id: ev.session_id,
    expect: "none",
    methods: [{
      method: "sendMessage",
      params: {
        text: "Pulsa el botón",
        reply_markup: { inline_keyboard: [[{ text: "Vamos", callback_data: "go" }]] },
      },
    }],
  }));
} else if (ev.type === "callback" && ev.event.callback_data === "go") {
  ws.send(JSON.stringify({
    type: "execute",
    session_id: ev.session_id,
    expect: "none",
    methods: [{ method: "sendMessage", params: { text: "¡Botón pulsado!" } }],
  }));
}

Qué sigue