Opciones de API para números de teléfono de Telegram: Bot API, Client API o una API de verificación de registro

Una comparación para desarrolladores entre la Telegram Bot API, la Telegram client API y una API de verificación de registro para tareas que involucran números de teléfono.

No existe una única API de números de teléfono de Telegram. La Telegram Bot API solo recibe un número de teléfono cuando un usuario decide compartirlo, la Telegram client API funciona a través de una cuenta de usuario real y sus credenciales, y una API de verificación de registro como TG Validator responde si un número enviado está registrado en Telegram. Elija la que se ajuste a su tarea: recopilar un número de un usuario dispuesto, automatizar su propia cuenta o verificar números que ya posee.

Qué entienden los desarrolladores por una API de números de teléfono de Telegram

Las búsquedas de "telegram phone number api" generalmente provienen de uno de estos tres trabajos:

1. Recopilar el número de un usuario dentro de un bot, por ejemplo, para vincular un chat de Telegram a una cuenta de cliente.
2. Automatizar una cuenta de usuario de Telegram, por ejemplo, para gestionar contactos o crear un cliente personalizado.
3. Verificar números que ya posee, por ejemplo, para marcar qué contactos de CRM tienen una cuenta de Telegram antes de elegir un canal.

Cada trabajo se asigna a una interfaz diferente con distintas credenciales, límites y responsabilidades. Elegir la incorrecta es la razón más común por la que las integraciones se detienen.

Bot API: recibir un número que el usuario decide compartir

La Telegram Bot API no busca usuarios por número de teléfono. Un bot recibe un número solo cuando el usuario lo envía:

• Un botón de teclado de respuesta con request_contact configurado solicita al usuario que comparta su propio número de teléfono como contacto. La referencia señala que esto funciona solo en chats privados.
• El mensaje compartido contiene un objeto Contact que incluye el número de teléfono y, opcionalmente, el identificador de Telegram del usuario.

Esta es la herramienta adecuada cuando desea que un cliente conecte su chat de Telegram a su servicio con una acción explícita por su parte. No puede verificar una lista de números, y los bots no pueden llamar al método de importación de contactos de la client API, que Telegram documenta como disponible solo para usuarios (contacts.importContacts).

Client API: automatizar una cuenta de Telegram real

La Telegram client API (MTProto) es la que utilizan las aplicaciones oficiales y de terceros. Bibliotecas como TDLib, Telethon y Pyrogram la envuelven, y la mayoría de los scripts de "verificación de números de teléfono" de código abierto están construidos sobre ella.

Antes de desarrollar sobre ella, tenga en cuenta lo que Telegram documenta en Obtaining api_id:

• Necesita un api_id y un api_hash de my.telegram.org, creados a partir de una cuenta de Telegram existente; cada número de teléfono puede estar vinculado a un solo api_id.
• Los clientes de terceros deben seguir los Términos de servicio de la API. Las cuentas que utilizan clientes no oficiales son puestas bajo observación, y el envío masivo o spam a través de la API puede llevar a una prohibición permanente.
• La importación de contactos los almacena en la cuenta que ejecuta el código.

La client API es adecuada para crear un cliente de Telegram genuino o automatizar su propia cuenta. Para verificar listas de contactos comerciales, significa que los datos de la empresa residen en la cuenta de una persona, y perder esa cuenta detiene el flujo de trabajo.

API de verificación de registro: responder si un número está en Telegram

Una API de verificación de registro está diseñada para el tercer trabajo. La API REST de TG Validator funciona sin necesidad de una cuenta de Telegram por su parte:

• Verificación única: POST /api/v1/check con un encabezado X-API-Key que contiene su clave con prefijo sk_. El cuerpo JSON nombra el tipo de servicio tg y el número de teléfono en formato E.164.
• Lotes pequeños: POST /api/v1/batch-check acepta hasta 100 números por solicitud.
• Flujo de respuesta inmediata: ambos endpoints devuelven resultados en la respuesta; no hay ninguna tarea que enviar o consultar.
• Sobre de respuesta: el sobre documentado envuelve cada respuesta con un código comercial y un mensaje. Un resultado completado le indica, en la misma respuesta, si el número que envió está registrado en Telegram. Una verificación que no se puede decidir devuelve un código comercial distinto de cero y ningún resultado completado.
• Saldo: GET /api/v1/balance permite que su servicio verifique el saldo restante antes de un trabajo grande.

La documentación actual de la API describe controles de concurrencia y tiempo de espera por usuario en lugar de un límite de solicitudes por minuto: hasta cinco verificaciones en curso, un tiempo de espera de 60 segundos para una verificación única y 300 segundos para una verificación de varios números, con una verificación de varios números por cuenta a la vez. Confirme esto en la documentación antes de ajustar los trabajadores, ya que pueden cambiar.

Para listas que superan ampliamente los 100 números, los endpoints de carga masiva asíncronos separados aceptan una carga de archivos TXT o CSV y devuelven un result.csv cuando finaliza la tarea.

Comparación de la API de números de teléfono de Telegram

Muchos productos combinan dos de estas opciones: un bot para hablar con los usuarios que dan su consentimiento y una verificación de registro para decidir qué contactos existentes invitar a través de Telegram.

Lista de verificación de integración para una API de verificación de registro

• Normalice primero. Convierta los números a E.164 (signo más, código de país, sin prefijo de tronco ni puntuación) antes de llamar a la API.
• Mantenga la clave en el lado del servidor. Nunca la incluya en una aplicación móvil o paquete de navegador, y gestione las claves desde el panel de control.
• Maneje tres resultados. Sí, no e indeterminado. Almacene las verificaciones indeterminadas por separado y vuelva a intentarlo más tarde en lugar de escribirlas como negativas.
• Respete la concurrencia. Ajuste los grupos de trabajadores al límite documentado de procesos en curso y reduzca la carga ante errores en lugar de reintentar en un bucle cerrado.
• Almacene la fecha de verificación. El registro es una señal en el momento de la verificación; guarde la fecha para que los resultados obsoletos puedan actualizarse.
• Presupueste para verificaciones decididas. Cada verificación decidida y completada se cobra a la tarifa aplicable independientemente de la respuesta, así que elimine duplicados antes de enviar.
• Clientes de IA: un endpoint MCP en https://tgvalidator.com/mcp expone las verificaciones de respuesta inmediata y el saldo a clientes compatibles con MCP, utilizando autenticación Bearer con la misma clave y saldo. Las tareas masivas permanecen en la API REST.

Preguntas frecuentes

¿Puede un bot de Telegram buscar a un usuario por número de teléfono?

No. Un bot recibe un número de teléfono solo cuando un usuario lo comparte, generalmente a través de un botón de teclado de respuesta que solicita el contacto en un chat privado. Verificar una lista de números requiere una cuenta de usuario en la client API o una API de verificación de registro.

¿Cómo pueden los equipos verificar el registro en Telegram sin una cuenta de Telegram?

Utilice una API de verificación de registro. TG Validator acepta un número E.164 en POST /api/v1/check, o hasta 100 números en POST /api/v1/batch-check, autenticado con un encabezado X-API-Key, y devuelve el resultado en la misma respuesta.

¿Existe un límite de tasa por minuto en la API de TG Validator?

No se publica ningún límite de solicitudes por minuto. La documentación describe controles de concurrencia y tiempo de espera por usuario, por lo que las integraciones deben ajustar los trabajadores a esos controles y consultar la documentación actual para ver si hay cambios.

¿Cómo pueden los equipos probar la API antes de un despliegue mayor?

Los usuarios registrados pueden contactar al soporte para recibir 100 verificaciones gratuitas, lo cual es suficiente para probar la normalización de entradas, el manejo de resultados indeterminados y el registro con una muestra pequeña.

Aprenda más

Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.

• Ver la documentación del producto →
• Hablar con el equipo →