Verificador de Números de Telegram — Verificar Contas em Lote via Plataforma ou API

Um verificador de números de Telegram processa números de telefone no formato E.164 e retorna um sinal do Telegram para cada linha. Use a tarefa básica tg quando você só precisar do status de registro. As verificações de atividade e de perfil público são produtos separados, com campos e custos diferentes; não presuma que o resultado básico os inclui.

Você pode executar um lote sem código na interface do produto Telegram ou automatizar listas recorrentes com a API REST descrita abaixo.

Escolha primeiro a profundidade do resultado do Telegram

Verificação	Tipo de tarefa da API	Resultado principal	Mais indicado para
Registro	`tg`	Número enviado e status de registro	Remover linhas não registradas e segmentação básica de listas
Atividade	`tg_active`	Registro mais identificadores disponíveis, horário da última visualização, dias ativos e status de membro	Segmentação interna por recência
Perfil público	`tg_avatar`	Registro mais perfil, avatar, atividade e atributos derivados da imagem disponíveis	Revisão autorizada de enriquecimento de perfil

Os campos opcionais de perfil podem ficar vazios. Idade e gênero derivados de um avatar público são estimativas probabilísticas, não fatos verificados, e não devem ser usados para tomar decisões relevantes sobre uma pessoa. A página do produto Telegram atual mostra os resultados configurados para cada nível.

Prepare o arquivo de entrada

Crie um arquivo .txt ou .csv com um número de telefone em formato internacional por linha. Mantenha no sistema de origem o seu próprio ID de registro estável, para que cada linha exportada possa ser associada de volta com segurança.

+14155550100
+41798284651
+447700900123

Valide os códigos de país e remova ramais antes do envio. Um erro de formatação deve ser tratado de forma diferente de um resultado confirmado de “não registrado”.

Envie uma tarefa de registro do Telegram

Referência oficial: Telegram Bulk CheckNumber API.

POST https://api.checknumber.ai/v1/tasks

Parâmetro	Descrição
`file`	Um número de telefone E.164 por linha
`task_type`	`tg` para a verificação básica de registro do Telegram

curl --location 'https://api.checknumber.ai/v1/tasks' \
  --header 'X-API-Key: API-KEY' \
  --form 'file=@"./numbers.txt"' \
  --form 'task_type="tg"'

Guarde o task_id retornado. Não exponha a chave de API em código do lado do cliente, logs do navegador, eventos de analytics ou capturas de tela compartilhadas.

Consulte a tarefa e baixe os resultados

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
  --header 'X-API-Key: API-KEY' \
  --form 'task_id="TASK_ID"'

Consulte com um intervalo razoável em vez de enviar requisições contínuas. Quando a tarefa chegar a exported, baixe o arquivo pelo result_url.

Campo da tarefa	Significado
`created_at`, `updated_at`	Data/hora de criação e do status mais recente
`task_id`	Identificador usado nas consultas de status
`status`	Por exemplo `pending`, `processing` ou `exported`
`total`	Linhas enviadas na tarefa
`success`, `failure`	Contagem de linhas concluídas e com falha
`result_url`	Local de download após a exportação

Na tarefa básica tg, as colunas de resultado importantes são o Number enviado e o veredito de registro telegram. Siga a documentação para as chaves de resposta atuais em vez de fixar no código campos de uma exportação antiga.

Trate falhas sem corromper a lista

Resposta	Cobrança descrita pela API	Comportamento da aplicação
`200`	Requisição bem-sucedida e cobrável	Salvar o ID da tarefa ou o status retornado
`400`	Não cobrado	Corrigir parâmetros ou formato do arquivo antes de tentar de novo
`500`	Não cobrado	Tentar novamente mais tarde com backoff

Mantenha três grupos no processamento posterior: registrado confirmado, não registrado confirmado e não resolvido/erro. Reprocessar apenas as linhas não resolvidas evita que uma falha temporária seja confundida com um resultado negativo do Telegram.

O que o registro no Telegram não comprova

Uma correspondência de registro não comprova que a conta está ativa recentemente, pertence à pessoa esperada, consente em ser contatada ou vai responder. Da mesma forma, um sinal de última visualização ou de perfil público pode estar ausente por questões de disponibilidade e privacidade.

Use a menor profundidade de resultado de que o seu fluxo precisa, documente por que os dados são processados e aplique os requisitos locais de privacidade e de contato. A CheckNumber.AI não precisa enviar mensagens ao número enviado para produzir o resultado de registro descrito.

Checklist de implementação

Normalize os números para E.164 e preserve um ID do registro de origem.
Escolha tg, tg_active ou tg_avatar de acordo com os campos necessários — não pela maior quantidade de campos disponíveis.
Envie uma tarefa específica da plataforma e salve o seu task_id.
Consulte com backoff até a tarefa chegar a um estado final.
Baixe os resultados prontamente e separe os resultados confirmados dos erros.
Revise a documentação oficial da API e os preços atuais antes do uso em produção.

Perguntas frequentes

Quanto tempo leva uma tarefa de um milhão de números?

O tempo de processamento varia conforme a carga do servidor e os limites de taxa da plataforma. Não projete uma integração com base em um tempo de conclusão garantido; acompanhe o status da tarefa.

A verificação envia uma mensagem no Telegram?

Não. A verificação de registro não envia mensagens nem notifica o número enviado.

Uma tarefa pode verificar o Telegram e outras plataformas?

Não. Cada tarefa é específica de uma plataforma. Envie tarefas separadas quando um fluxo precisar de resultados de mais de uma plataforma.

O que acontece se o crédito disponível for insuficiente?

As linhas processadas com sucesso consomem crédito. Revise os status retornados da tarefa e de cada linha em vez de presumir que todas as linhas enviadas foram concluídas.

Verificador de Números de Telegram — Verificar Contas em Lote via Plataforma ou API | CheckNumber.AI