API de Telegram: conectar un bot, enviar y recibir mensajes

28 de octubre de 2026 · Equipo Zoosial

La API de Telegram de Zoosial conecta un bot que tú creas con @BotFather, sin OAuth: le pasas el token y el canal o grupo donde el bot es administrador. Con él puedes publicar en ese canal con POST /posts, leer los chats que le escriben al bot, responderles y enviar cobros con Telegram Stars. Los pagos confirmados llegan a tu servidor por webhook.

Qué puedes hacer

• Conectar el bot: POST /connect/telegram.
• Publicar en el canal o grupo: POST /posts. Sin mediaUrls envía texto; con una URL de imagen o video, envía el archivo con el texto como pie.
• Listar los chats que han escrito: GET /accounts/:id/telegram/conversations, que devuelve chatId, username, lastText y lastAt por chat.
• Leer los mensajes de un chat: GET /accounts/:id/telegram/conversations/:chatId/messages, en orden cronológico ascendente.
• Responder a un chat: POST /accounts/:id/telegram/messages con { recipientId, text }.
• Cobrar con Telegram Stars: POST /accounts/:id/telegram/invoice con { chatId, title, description, priceXTR }.

Cómo conectar la cuenta

Telegram no pasa por un flujo OAuth de navegador. Creas el bot con @BotFather y llamas a POST /connect/telegram con profileId, botToken y chatId. El chatId es el @canal o el id numérico del grupo o canal, y el bot debe ser administrador ahí. Zoosial valida el token al conectar.

Ejemplo

Conectar el bot a un canal y publicar (los identificadores son ilustrativos):

# Conectar el bot a un canal
curl -X POST https://zoosial.com/connect/telegram \
  -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \
  -d '{"profileId":"prof_123","botToken":"123456:ABC-token","chatId":"@micanal"}'

# Publicar en el canal
curl -X POST https://zoosial.com/posts \
  -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \
  -d '{"platforms":[{"accountId":"acc_tg_1"}],"content":"Nuevo anuncio en el canal","publishNow":true}'

Por MCP

No hay una herramienta MCP específica de Telegram. Con las genéricas, un agente puede usar list_accounts, accounts_health y create_post para publicar en el canal conectado. Las herramientas de mensajes publicadas son list_conversations y send_dm (solo Facebook e Instagram) y send_whatsapp; no cubren Telegram. Conversaciones, mensajes e invoice no tienen herramienta MCP propia. Ver Servidor MCP.

Reglas y límites

• El bot debe ser administrador del canal o grupo donde publica.
• La Bot API de Telegram no tiene un endpoint para "listar chats". Zoosial arma la bandeja con el registro de los mensajes que le llegan, así que solo aparecen los chats cuyos mensajes ya llegaron a Zoosial.
• Los cobros con Stars (moneda XTR) requieren un plan de pago; en otro caso responde 403 telegram_stars_not_in_plan. Zoosial no cobra comisión de plataforma: el bot se queda con el 100%.
• POST /accounts/:id/telegram/invoice solo dispara la invoice y no espera el pago. La confirmación llega por el webhook de salida payment.received, con { accountId, chatId, amount, currency, chargeId, platform }.
• Los webhooks de salida van firmados (ver Webhooks).
• El evento message.received está documentado para Messenger, Instagram y WhatsApp, no para Telegram.
• Una cuenta de Telegram por perfil.

Precio

Conectar el bot, publicar y leer la bandeja no requieren plan de pago: el plan gratis cuesta $0, trae un perfil con hasta 3 cuentas y no vence. El plan de pago cobra por perfil ($95 MXN al mes más IVA por perfil, el primero gratis) e incluye los cobros con Telegram Stars; el gratis y la prueba de 14 días no. Ver precios y Bandeja unificada.

Compáralo

Si comparas proveedores de API para redes sociales, revisa la comparativa y la guía cómo elegir una API para conectar redes sociales, que compara redes y mensajería.

Preguntas frecuentes

← Todas las integraciones