Opções de API de número de telefone do Telegram: Bot API, Client API ou uma API de verificação de registro

Uma comparação para desenvolvedores sobre a Bot API do Telegram, a Client API do Telegram e uma API de verificação de registro para trabalhos que envolvem números de telefone.

Não existe uma única API de número de telefone do Telegram. A Bot API do Telegram só recebe um número de telefone quando um usuário escolhe compartilhá-lo, a Client API do Telegram funciona por meio de uma conta de usuário real e suas credenciais, e uma API de verificação de registro, como o TG Validator, responde se um número enviado está registrado no Telegram. Escolha a que corresponde à sua tarefa: coletar um número de um usuário disposto, automatizar sua própria conta ou verificar números que você já possui.

O que os desenvolvedores entendem por API de número de telefone do Telegram

As buscas por "telegram phone number api" geralmente surgem de um destes três trabalhos:

1. Coletar o número de um usuário dentro de um bot, por exemplo, para vincular um chat do Telegram a uma conta de cliente.
2. Automatizar uma conta de usuário do Telegram, por exemplo, para gerenciar contatos ou criar um cliente personalizado.
3. Verificar números que você já possui, por exemplo, para sinalizar quais contatos do CRM possuem uma conta no Telegram antes de escolher um canal.

Cada trabalho é mapeado para uma interface diferente com credenciais, limites e responsabilidades distintas. Escolher a errada é o motivo mais comum para o travamento de integrações.

Bot API: recebendo um número que o usuário escolhe compartilhar

A Bot API do Telegram não pesquisa usuários por número de telefone. Um bot recebe um número apenas quando o usuário o envia:

• Um botão de teclado de resposta com request_contact definido solicita que o usuário compartilhe seu próprio número de telefone como um contato. A referência observa que isso funciona apenas em chats privados.
• A mensagem compartilhada carrega um objeto Contact contendo o número de telefone e, opcionalmente, o identificador do Telegram do usuário.

Esta é a ferramenta certa quando você deseja que um cliente conecte seu chat do Telegram ao seu serviço com uma ação explícita por parte dele. Ela não pode verificar uma lista de números, e bots não podem chamar o método de importação de contatos da Client API, que o Telegram documenta como disponível apenas para usuários (contacts.importContacts).

Client API: automatizando uma conta real do Telegram

A Client API do Telegram (MTProto) é o que os aplicativos oficiais e de terceiros usam. Bibliotecas como TDLib, Telethon e Pyrogram a encapsulam, e a maioria dos scripts de "verificador de número de telefone" de código aberto são construídos sobre ela.

Antes de desenvolver sobre ela, observe o que o Telegram documenta em Obtaining api_id:

• Você precisa de um api_id e api_hash do my.telegram.org, criados a partir de uma conta existente do Telegram; cada número de telefone pode ser vinculado a apenas um api_id.
• Clientes de terceiros devem seguir os Termos de Serviço da API. Contas que usam clientes não oficiais são colocadas sob observação, e o envio de spam ou inundações (flooding) por meio da API pode levar a um banimento permanente.
• A importação de contatos os armazena na conta que executa o código.

A Client API é adequada para criar um cliente genuíno do Telegram ou automatizar sua própria conta. Para verificar listas de contatos comerciais, isso significa que os dados da empresa ficam na conta de uma pessoa, e perder essa conta interrompe o fluxo de trabalho.

API de verificação de registro: respondendo se um número está no Telegram

Uma API de verificação de registro é feita para o terceiro trabalho. A API REST do TG Validator funciona sem qualquer conta do Telegram do seu lado:

• Verificação única: POST /api/v1/check com um cabeçalho X-API-Key contendo sua chave com prefixo sk_. O corpo JSON nomeia o tipo de serviço tg e o número de telefone no formato E.164.
• Pequenos lotes: POST /api/v1/batch-check aceita até 100 números por solicitação.
• Fluxo de resposta única: ambos os endpoints retornam resultados na resposta; não há tarefa para enviar ou consultar.
• Envelope de resposta: o envelope documentado envolve cada resposta com um código de negócio e uma mensagem. Um resultado concluído informa, na mesma resposta, se o número que você enviou está registrado no Telegram. Uma verificação que não pode ser decidida retorna um código de negócio diferente de zero e nenhum resultado concluído.
• Saldo: GET /api/v1/balance permite que seu serviço verifique o saldo restante antes de um trabalho grande.

A documentação atual da API descreve controles de simultaneidade e tempo limite por usuário, em vez de um limite de solicitações por minuto: até cinco verificações em andamento, um tempo limite de 60 segundos para uma verificação única e 300 segundos para uma verificação de vários números, com uma verificação de vários números por conta de cada vez. Confirme esses dados na documentação antes de ajustar os workers, pois eles podem mudar.

Para listas muito além de 100 números, os endpoints de processamento em lote assíncronos separados aceitam um upload TXT ou CSV e retornam um result.csv quando a tarefa termina.

Comparação da API de número de telefone do Telegram

Muitos produtos combinam dois deles: um bot para falar com usuários que optam por participar e uma verificação de registro para decidir quais contatos existentes convidar pelo Telegram.

Lista de verificação de integração para uma API de verificação de registro

• Normalize primeiro. Converta números para E.164 (sinal de mais, código do país, sem prefixo de tronco ou pontuação) antes de chamar a API.
• Mantenha a chave no lado do servidor. Nunca a envie em um aplicativo móvel ou pacote de navegador, e gerencie as chaves a partir do painel.
• Lide com três resultados. Sim, não e indeterminado. Armazene verificações indeterminadas separadamente e tente novamente mais tarde, em vez de gravá-las como negativas.
• Respeite a simultaneidade. Dimensione os pools de workers para o limite documentado de verificações em andamento e reduza a frequência em caso de erros, em vez de tentar novamente em um loop fechado.
• Armazene a data da verificação. O registro é um sinal no momento da verificação; mantenha a data para que resultados obsoletos possam ser atualizados.
• Orce para verificações decididas. Cada verificação decidida e concluída é cobrada na taxa aplicável, independentemente da resposta, portanto, deduplique antes de enviar.
• Clientes de IA: um endpoint MCP em https://tgvalidator.com/mcp expõe as verificações de resposta única e o saldo para clientes compatíveis com MCP, usando autenticação Bearer com a mesma chave e saldo. Tarefas em lote permanecem na API REST.

Perguntas frequentes

Um bot do Telegram pode pesquisar um usuário por número de telefone?

Não. Um bot recebe um número de telefone apenas quando um usuário o compartilha, normalmente por meio de um botão de teclado de resposta que solicita o contato em um chat privado. Verificar uma lista de números requer uma conta de usuário na Client API ou uma API de verificação de registro.

Como as equipes podem verificar o registro no Telegram sem uma conta no Telegram?

Use uma API de verificação de registro. O TG Validator aceita um número E.164 em POST /api/v1/check, ou até 100 números em POST /api/v1/batch-check, autenticado com um cabeçalho X-API-Key, e retorna o resultado na mesma resposta.

Existe um limite de taxa por minuto na API do TG Validator?

Nenhum limite de solicitação por minuto é publicado. A documentação descreve controles de simultaneidade e tempo limite por usuário, portanto, as integrações devem dimensionar os workers para esses controles e verificar a documentação atual para alterações.

Como as equipes podem testar a API antes de uma implementação maior?

Usuários registrados podem entrar em contato com o suporte para receber 100 verificações gratuitas, o que é suficiente para testar a normalização de entrada, o tratamento de resultados indeterminados e o registro em uma pequena amostra.

Saiba mais

Escolha as informações do produto que se encaixam na próxima etapa do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →