Telegrama

Importante: Los “bots” de Telegram son cuentas especiales controladas por un token, no por un número de teléfono. Se puede agregar un solo bot a muchos grupos o canales, pero cada mensaje debe llegar al bot (a través de una mención directa, una respuesta o una publicación en el canal) para que la IA responda.

​

🔢 Tabla de contenidos

1. Create a Telegram Bot with BotFather
2. Retrieve the Bot HTTP Token
3. Add & Promote the Bot in Chats / Channels
4. Configure Webhooks in Telegram
5. Connect Your Bot to ZappWay
6. Send a Test Message
7. Monitoring & Maintenance

​

1. Crea un bot de Telegram con BotFather

1. Open Telegram (desktop or mobile).
2. Search for @BotFather and open the verified account.
3. Tap Start (or send /start). BotFather displays a menu of commands.
4. Send /newbot.
5. Follow the prompts:

• Nombre del bot: el nombre completo que se muestra a los usuarios (por ejemplo, “Soporte ZappWay”).
  • Nombre de usuario: debe terminar con bot (por ejemplo, zappway_support_bot).

6. BotFather responde con:
   Done! Congratulations on your new bot.
   Use this token to access HTTP API:
   123456789:AAE-YourLongTokenHere
   

Consejo: Tu bot es público de forma predeterminada. Si prefiere ocultarlo de la búsqueda, envíe /setprivate a BotFather.

​

2. Recuperar el token HTTP del bot

• Si perdiste el token, abre BotFather y envía /token, luego elige tu bot.
• Almacenar el token de forma segura (administrador de contraseñas, bóveda); Cualquiera con este token puede controlar el bot.

​

3. Agregar y promocionar el bot en chats/canales

​

3.1 Chat de soporte privado (opcional)

1. Open a 1-on-1 chat with your bot.
2. Send /start so the bot is allowed to message you.

​

3.2 Chat de soporte grupal

1. Create or open the group where customers will send messages.
2. Tap the group title ➜ Add Member ➜ search your bot’s username ➜ Add.
3. Promote it to Administrator (required so it can read and send all messages).

• Permisos necesarios: Leer mensajes, Enviar mensajes, Administrar mensajes (opcional).

​

3.3 Canal Público o Privado

1. Open the channel ➜ Manage ➜ Administrators ➜ Add Admin ➜ select your bot.
2. Grant Post Messages permission so the AI can publish replies.

¿Por qué administrador? Telegram solo entrega todos los mensajes a los bots que son administradores; de lo contrario, el bot solo ve menciones.

​

4. Configurar Webhooks en Telegram

1. Copy the Callback URL and Verify Token shown in ZappWay (you will get them in Step 5).
2. Send this HTTPS request (you can use a browser address bar):

https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook
  ?url=<CALLBACK_URL>
  &secret_token=<VERIFY_TOKEN>

• Reemplace <YOUR_TOKEN>, <CALLBACK_URL>, <VERIFY_TOKEN> con valores reales.
• Telegram responde con {"ok":true, "result":true, ...} si el webhook está configurado.

Nota:

• La URL debe utilizar HTTPS con un certificado válido.
• Un solo bot puede apuntar a un webhook a la vez. Al llamar nuevamente a setWebhook se sobrescribe la URL anterior.

​

5. Conecte su bot a ZappWay

1. Sign in to ZappWay ➜ Integrations ➜ Telegram ➜ Add Telegram Integration.
2. Paste the HTTP Token you copied from BotFather. Click Continue.

• ZappWay valida el token con el punto final getMe de Telegram.

3. ZappWay now displays two read-only fields:

• URL de devolución de llamada: el punto final que acaba de configurar en el Paso 4
  • Verificar token: el secret_token que pasaste a setWebhook

4. Click Save. The integration status changes to “Waiting for updates”.

Si ZappWay muestra “Credenciales no válidas”, vuelva a verificar el token en BotFather y repita el Paso 5.

​

6. Enviar un mensaje de prueba

1. From any Telegram account, send “Hello” to:

• el bot directamente o
  • un grupo/canal donde el bot es administrador.

2. En ZappWay ➜ Bandeja de entrada, deberías ver el mensaje entrante.
3. Si configuró flujos de respuesta automática, el empleado de IA debería responder automáticamente.

Solución de problemas: ¿No hay ningún mensaje en la bandeja de entrada?

• Confirme el estado del webhook con https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo.
• last_error_message revelará problemas de SSL o de red.
• Asegúrese de que el bot tenga permiso para leer mensajes de grupo/canal (rol de administrador).

​

7. Monitoreo y mantenimiento

​

7.1 Estado del webhook

• getWebhookInfo devuelve los campos pending_update_count y ​​last_error_date/message.
• Un last_error_date distinto de cero significa que Telegram no pudo PUBLICAR en ZappWay. Verifique el firewall/SSL.

​

7.2 Seguridad del token

• Los tokens nunca caducan automáticamente, pero los revocan inmediatamente si se filtran: /revoke comando en BotFather ➜ Requiere configurar un nuevo webhook.

​

7.3 Escala y límites

• Los bots de Telegram pueden enviar 30 mensajes/segundo en total y 1 mensaje/segundo por chat.
• Los archivos adjuntos grandes (videos, documentos) se entregan como ID de archivo; ZappWay obtiene contenido a pedido.

​

7.4 Errores comunes

​

✅ Notas finales

• Un webhook por bot: si experimentas con la preparación, recuerda volver a la URL de producción.
• Modo de privacidad: de forma predeterminada, los bots no ven todos los mensajes del grupo. La promoción del administrador desactiva el modo de privacidad para que la IA pueda leer el contexto completo.
• Pruebas: prueba siempre primero en un chat privado, luego en un grupo pequeño, antes de implementarlo en canales públicos.
• Seguridad: nunca compartas tu token en capturas de pantalla o registros.

​

Enlaces útiles

• Documentación de la API de Telegram Bot: https://core.telegram.org/bots/api
• Referencia del comando BotFather: https://core.telegram.org/bots#botfather
• Guía de configuración de webhooks: https://core.telegram.org/bots/webhooks