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
- Abre Integraciones en el menú izquierdo y pulsa Agregar integración.
- Selecciona Procesador externo y dale un nombre.
- 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.
- URL de conexión: tiene la forma
Parámetros adicionales de la integración que afectan al protocolo:
session_ttl_seconds— tiempo de vida de la sesión en segundos (por defecto3600).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_nameyusernameopcionales, yparams, un mapa de parámetros del usuario, incluidos los recibidos mediante un enlace.chat:id(int64) ytype, por ejemplo"private".update: evento Telegram Update original en JSON. Está presente ensession.open,messageycallback.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 elupdateoriginal, eleventnormalizado completo y losuser.params.message: llega cuando el servicio espera un mensaje (expect=text/any) y la persona responde. Contiene los mismos datos quesession.open.callback: se pulsó un botón enviado antes por el servicio.updatecontiene el evento original; enusersolo estátg_user_id;eventcontiene únicamente elcallback_dataque el servicio puso en el botón:
{ "callback_data": "<valor original definido por el servicio en el botón>" }
session.cancel/session.expired: solo incluyensession_id,bot_id,user.tg_user_idychat.id(encancel, tambiénchat.type). No incluyenupdatenievent. 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 paratype: "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 ejemplosendMessage, y sus parámetros.expect: indica si el servicio espera otra respuesta:"none","text"o"any". Un valor vacío equivale anone.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
executepor 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_idofrom_chat_iddentro deparamscontiene un valor distinto de0y del chat de la sesión, se rechaza ese método. Puedes omitirchat_id: GetMyBot añadirá el del diálogo actual. - Botones inline con
callback_datase tokenizan automáticamente (formato internox:<token>); el tiempo de vida del botón es hasta que expire la sesión. Los botonesurl/webapp/switch_inlineno 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=textoany: el siguiente mensaje del usuario llega al servicio como eventomessage.expect=noney sin botones de callback: la sesión se cierra automáticamente. El mensaje es el último de ese diálogo.expect=nonepero 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.
Límites del diálogo
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 comomessagesin activar las reacciones normales del bot. - Pulsación de un botón tokenizado: llega como
callbackcon elcallback_dataoriginal. GetMyBot confirma la pulsación conanswerCallbackQueryy verifica el bot, usuario y chat de la sesión. Pulsar el botón no cierra la sesión. /cancel(también/cancel@boty la palabra rusaотмена) con una sesión externa activa: se cierra la sesión, se envíasession.cancelal 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.cancelpara la sesión desplazada. - Fin del TTL: la sesión pasa a
expiredy se envíasession.expiredsi 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_secondsde la integración). - Frecuencia de comandos: 60
executepor 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:
pingcada 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 enviarpingopong. 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
messageycallbackpendientes 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.cancelysession.expiredno 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_iddel 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
- Integraciones — visión general de los servicios conectables.
- Reacciones — cómo se construyen disparadores, condiciones y acciones.
- Solicitudes web y webhooks — forma más sencilla de llamar a una URL externa sin diálogo.