Encontrando o nome de usuário do Telegram por trás de uma lista de números de telefone

Um guia para adicionar nomes de usuário do Telegram a uma lista de números de telefone específica de um país com o serviço em lote tg_active_batch, incluindo preparação de arquivos, colunas do result.csv, nomes de usuário vazios e uso responsável.

Para encontrar o nome de usuário do Telegram associado a números de telefone em uma lista de negócios, processe a lista por meio de uma tarefa de atividade em lote, como o tg_active_batch do TG Validator, que retorna o status de registro no Telegram, além de uid, nome de usuário e activedays para cada número. A coluna de nome de usuário fica vazia sempre que uma conta não possui um nome de usuário público, pois os nomes de usuário são opcionais no Telegram. Trate o resultado como enriquecimento de lista para registros que a equipe já possui, e não como uma forma de pesquisar pessoas desconhecidas.

Por que as equipes buscam o nome de usuário do Telegram por número de telefone

A maioria dos guias para este termo descreve o caminho do consumidor: salvar o número nos contatos, abrir o perfil no aplicativo e ler o nome de usuário, se houver um. Isso funciona para um amigo. Não funciona para uma exportação de CRM com vários milhares de leads, e isso encaminha dados de negócios através da agenda pessoal de um membro da equipe.

As equipes de negócios geralmente têm um objetivo diferente:

• As equipes de suporte desejam um nome de usuário para que os agentes possam vincular ao perfil do Telegram de um cliente com um link t.me quando o cliente solicitar contato por esse meio.
• As equipes de comunidade e crescimento desejam combinar contatos existentes com identificadores que já aparecem em seus próprios grupos ou canais.
• As equipes de CRM desejam uma chave estável do Telegram ao lado de cada registro de telefone para que duplicatas possam ser mescladas.

Todos os três são trabalhos de enriquecimento em registros que a organização já possui. Esse enquadramento é importante para o método e para como os dados são usados posteriormente.

Como os nomes de usuário e números de telefone do Telegram se relacionam

No Telegram, um número de telefone cria a conta, enquanto um nome de usuário é um identificador público opcional. O Telegram FAQ explica que os usuários não precisam de um nome de usuário, podem definir ou remover um nas Configurações e podem compartilhar links t.me para que outros os alcancem sem ver seu número. Os usuários também decidem quem pode ver seu número de telefone e quem pode encontrá-los por meio dele.

Duas consequências práticas decorrem disso:

1. Muitas contas não possuem nome de usuário, portanto, uma coluna de nome de usuário vazia é um resultado normal, não um erro.
2. Nomes de usuário podem mudar ou ser removidos. Um identificador capturado hoje deve conter a data em que foi capturado.

O uid do Telegram é diferente: é o identificador numérico da conta e não muda quando um nome de usuário é alterado. Isso torna o uid uma chave de junção melhor para desduplicação do que o nome de usuário.

Qual serviço do TG Validator retorna nomes de usuário

A Verificação de registro no Telegram para um único número, no painel ou por meio de POST /api/v1/check, retorna apenas o status de registro no Telegram. É a ferramenta certa para decidir se um número possui uma conta no Telegram, mas não retorna nomes de usuário.

Os nomes de usuário vêm do serviço de atividade em lote assíncrono, tg_active_batch. Para cada número de telefone, ele retorna:

Colunas extras dependem do tipo de serviço e podem estar vazias para algumas linhas. Se a equipe também precisar de URLs de avatar e estimativas baseadas em avatar, o tg_profile_batch é o serviço de perfil separado; para este trabalho, o tg_active_batch é a escolha focada.

Passo a passo: da lista de telefones à coluna de nome de usuário

1. Escolha um país por arquivo. As tarefas em lote de números de telefone exigem um país selecionado, e o arquivo deve ser essencialmente composto por números desse país. Se 10% ou mais dos números usarem outros códigos de país, o arquivo será rejeitado, portanto, divida listas mistas por país primeiro.
2. Normalize para o formato internacional. Use códigos de país conforme definido na ITU-T Recommendation E.164, remova zeros de tronco, espaços e símbolos, e desduplique.
3. Salve como TXT ou CSV com um número por linha. Limites por produto sobre tamanho de arquivo e entradas se aplicam; verifique a documentação da API atual.
4. Crie a tarefa na área de Verificação em Lote do painel ou com POST /api/v1/bulk-tasks, selecionando tg_active_batch e o país.
5. Aguarde a conclusão da tarefa. A tarefa relata processamento, sucesso ou falha. Ao consultar por meio da API, não faça consultas com frequência superior a uma vez a cada 30 segundos.
6. Baixe o result.csv e junte-o à lista de origem na coluna identifier.

O saldo é reservado quando a tarefa é enviada. Quando a tarefa é concluída, as entradas que retornaram resultados são cobradas e a reserva não utilizada é liberada; uma tarefa com falha libera sua reserva total.

Números da China continental (+86), Hong Kong (+852) e Macau (+853) não são suportados em tarefas de arquivo em lote, portanto, mantenha-os fora do upload.

Lendo e armazenando os resultados de nome de usuário

Uma vez que o result.csv seja unido à lista, classifique as linhas em grupos práticos:

• Conta presente, nome de usuário presente. Armazene o nome de usuário e o uid em campos de CRM dedicados com a data da tarefa.
• Conta presente, nome de usuário vazio. A conta existe, mas não possui um identificador público. Mantenha o uid para desduplicação e deixe o campo de nome de usuário em branco em vez de inventar um valor.
• Sem conta. Marque o campo do Telegram e mantenha o número para outros canais.
• Colunas vazias por outros motivos. Algumas colunas extras podem estar vazias para algumas linhas; trate-as como desconhecidas, não como zero.

Alguns hábitos de armazenamento evitam confusão posteriormente:

• Armazene nomes de usuário sem o @ inicial e normalize para letras minúsculas, já que os nomes de usuário do Telegram não diferenciam maiúsculas de minúsculas.
• Realize mesclagens baseadas no uid quando presente, porque um nome de usuário pode ser alterado ou liberado.
• Mantenha activedays como um valor aproximado com sua data; ele descreve os dias desde a última atividade, não se a pessoa está online agora.
• Atualize o enriquecimento em um cronograma que se ajuste ao fluxo de trabalho em vez de tratar uma execução como permanente.

Enriquecimento de lista, não uma pesquisa de pessoa

Um nome de usuário informa a uma equipe qual identificador público está anexado a uma conta do Telegram para um número que ela já possui. Ele não revela quem possui o telefone, não confirma que um lead é quem diz ser e não é uma permissão para enviar mensagens.

Equipes responsáveis definem algumas regras internas antes de executar o enriquecimento:

• Apenas enriqueça números coletados para um propósito que cubra contato ou suporte via Telegram.
• Limite as colunas mantidas ao que o fluxo de trabalho utiliza. A orientação do ICO do Reino Unido sobre data minimisation solicita que os dados pessoais sejam adequados, relevantes e limitados ao que é necessário.
• Corrija ou remova valores desatualizados, de acordo com o accuracy principle do ICO.
• Respeite os usuários que optaram por não definir um nome de usuário; um campo vazio é uma escolha deles, não uma lacuna a ser preenchida por outros meios.

Essas regras são exemplos de política interna, não aconselhamento jurídico para uma jurisdição específica.

FAQ

Por que a coluna de nome de usuário está vazia para alguns números que possuem uma conta no Telegram?

Os nomes de usuário são opcionais no Telegram. Quando uma conta não possui um nome de usuário público, o tg_active_batch ainda relata o status de registro e outras colunas disponíveis, mas a coluna de nome de usuário permanece vazia.

Uma verificação de número único pode retornar um nome de usuário do Telegram?

Não. A Verificação de registro no Telegram para um único número retorna apenas o status de registro. Nomes de usuário, uid e activedays vêm do serviço em lote tg_active_batch.

Como as equipes podem usar nomes de usuário que já possuem para enriquecer registros?

Quando a lista inicial contém nomes de usuário em vez de números de telefone, o serviço separado tg_username_batch verifica se esses nomes de usuário pertencem a contas existentes, e o tg_username_profile_batch adiciona uid, activedays e URL de avatar. Tarefas de nome de usuário não precisam de país e aceitam identificadores com ou sem @.

Uma equipe deve usar como chave de registros de CRM o nome de usuário do Telegram ou o uid?

O uid é a melhor chave porque permanece o mesmo quando um usuário altera ou remove um nome de usuário. Armazene o nome de usuário como um campo de exibição com a data em que foi capturado.

Saiba mais

Escolha as informações do produto que se ajustam ao próximo passo em seu fluxo de trabalho.

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