Esta guía lo lleva desde la cuenta hasta el primer envío. Elija bot para producción o cuenta personal solo cuando un bot no encaje.
En breve
- Bot: @BotFather token, instancia ACTIVA inmediatamente, el usuario debe haber enviado
/start primero
- Cuenta personal: crea la instancia, escanea el QR (o comparte el enlace) hasta que el estado sea ACTIVO
- Ambos modos utilizan la misma API de envío; solo la conexión difiere
¿No estás seguro de cuál elegir? Ver Modos de conexión.
Antes de empezar
- Una clave API (
sk_live_... o sk_test_... para sandbox)
- Instancia y envío de alcances en la clave, Scopes
- Reemplace
sk_live_xxxxx y https://api.notifique.dev en los ejemplos.
Just getting started? Use sk_test_... and check Sandbox.
En Telegram, el usuario debe hablar primero con el bot (/start). Sin eso, los envíos suelen fallar, política de Bot API.
1. Conecta el bot
Tres caminos, elige el que mejor se adapte a tu integración:1A, a través del tablero
- Telegram → Nueva instancia → Bot
- Pegue el @BotFather token
- Cuando el estado es activo, tenga en cuenta el ID de instancia y
@botUsername.
1B, vía API con token
Respuesta esperada: 200 con estado ACTIVO:Invalid token → TELEGRAM_BOT_TOKEN_INVALID. Save the id.webhookUrl es informativo. Notifique ya registra este punto final con la API Bot de Telegram, no necesita alojar ni configurar nada con esa URL. Es para auditoría y depuración (donde Telegram entrega actualizaciones).
2. Ask the user to start the bot
Share https://t.me/YOUR_BOT and ask them to tap Start (/start).List users who already started:Utilice chatId o @username de la respuesta en to.3. Envía un mensaje de texto
to es una matriz (hasta 100 destinatarios). Puedes usar @username si el chat ya existe.Respuesta esperada: 202:Utilice una cuenta personal sólo cuando un bot no encaje. La automatización masiva de DM viola los términos de Telegram. Se requiere acceptUserTerms: true.
1. Create instance and connect
Four paths, pick what fits your integration:1A, Via dashboard
- Telegram → New instance → Account (USER)
- Accept the displayed terms of use
- Scan the QR in the Telegram app or open the login link
- When status is active, note the instance id
1B, Via API with QR in your UI
Creates the connection and returns the QR in connection, same idea as unofficial WhatsApp:Expected response: 200 with PENDING status and QR in connection:Utilice connection.base64 para mostrar el QR en su interfaz de usuario o abra connection.loginUrl en la aplicación Telegram.1C, vía API con enlace para que el cliente lo escanee
Pase generateShareableLink: true para obtener también un enlace alojado, útil cuando la persona que escanea no está en su pantalla:Respuesta esperada: 200 con QR y enlace para compartir:Send shareableLink.hostedUrl to the customer. When they finish login, status becomes active.Cualquiera que tenga el enlace puede autenticar la sesión en esta instancia. Después de su uso, gire el secreto con POST /v1/telegram/instances/:instanceId/connect-page/rotate-secret.
1D, Via API with session string
Useful with 2FA or when interactive QR does not work, create the USER instance first, then:Instance becomes ACTIVE. 409 if QR is already running in parallel: TELEGRAM_QR_LOGIN_IN_PROGRESS.Resumen: panel para la ruta más sencilla; API con QR para incrustar el código en tu UI; generateShareableLink: true cuando alguien más necesita escanear; sesión cuando QR no funciona.
2. Refresh the QR (if it expires)
QR codes expire quickly. Request a new one without creating a new instance:Mientras prepara (CONNECTING):QR ready (WAITING_QR):También puedes recibir un nuevo QR a través de webhook (telegram.instance.qrcode).3. Recupera el enlace para compartir más tarde
¿Perdiste el hostedUrl de crear? Consultar o habilitar nuevamente, mismo patrón que WhatsApp:Verificar estado (Las URL solo aparecen si el secreto todavía está disponible en el servidor):Enable or regenerate (returns shareableLink):Expected response: 200 with hostedUrl and embedUrl.Invalidate old links (if the link leaked or the customer already connected):Desactivar la página pública:4. Send a text message
With an ACTIVE instance:Expected response: 202 (same shape as the Bot tab).
After your first send
- List sent:
GET /v1/telegram/messages
- Cancel in queue:
POST /v1/telegram/messages/:id/cancel (telegram.cancelled webhook)
- Inbound:
GET /v1/telegram/messages/inbound, configure in Settings → Received messages
- Webhooks:
telegram.sent, telegram.received, telegram.failed, do not use message.* (WhatsApp). Guide: Webhook events
Todos los tipos de envío
En la referencia de la API (pestaña Telegram), abra Enviar mensaje en Telegram y elija un ejemplo en el playground: Texto, Imagen, Vídeo, Audio, Documento, Ubicación, Plantilla, Programada.
Próximos pasos
