Inicio rápido

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.

Bot
Personal account

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 500 destinatarios). Puedes usar @username si el chat ya existe.Respuesta esperada: 202:

{
  "success": true,
  "data": {
    "messageIds": ["cltg1..."],
    "messageId": "cltg1...",
    "count": 1,
    "status": "QUEUED",
    "scheduledAt": null
  }
}

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.

API Telegram

Instancias

Mensagens

Instâncias

En breve

Antes de empezar

1. Conecta el bot

1A, a través del tablero

1B, vía API con token

2. Ask the user to start the bot

3. Envía un mensaje de texto

1. Create instance and connect

1A, Via dashboard

1B, Via API with QR in your UI

1C, vía API con enlace para que el cliente lo escanee

1D, Via API with session string

2. Refresh the QR (if it expires)

3. Recupera el enlace para compartir más tarde

4. Send a text message

After your first send

Todos los tipos de envío

Próximos pasos

​En breve

​Antes de empezar

​1. Conecta el bot

​1A, a través del tablero

​1B, vía API con token

​2. Ask the user to start the bot

​3. Envía un mensaje de texto

​1. Create instance and connect

​1A, Via dashboard

​1B, Via API with QR in your UI

​1C, vía API con enlace para que el cliente lo escanee

​1D, Via API with session string

​2. Refresh the QR (if it expires)

​3. Recupera el enlace para compartir más tarde

​4. Send a text message

​After your first send

​Todos los tipos de envío

​Próximos pasos

En breve

Antes de empezar

1. Conecta el bot

1A, a través del tablero

1B, vía API con token

2. Ask the user to start the bot

3. Envía un mensaje de texto

1. Create instance and connect

1A, Via dashboard

1B, Via API with QR in your UI

1C, vía API con enlace para que el cliente lo escanee

1D, Via API with session string

2. Refresh the QR (if it expires)

3. Recupera el enlace para compartir más tarde

4. Send a text message

After your first send

Todos los tipos de envío

Próximos pasos