Recebendo códigos SMS do Truecaller de forma programática

Como é a cadeia de chamadas de API para o Truecaller?

O id de serviço do Truecaller é truecaller, e todas as chamadas abaixo são feitas em https://otproute.com/api/v1 com uma chave Bearer cujo prefixo é or_live_.

1. GET /api/v1/countries fornece os ids dos países; guarde-os em cache.
2. GET /api/v1/prices?country=<id>&service=truecaller retorna o preço atual e se há uma rota aberta neste momento.
3. POST /api/v1/activations com {"service": "truecaller", "country": "in"} (ou qualquer outro id de país) reserva o número e devolve um id de ativação.
4. Digite esse número no app do Truecaller no seu dispositivo de teste e peça a verificação.
5. O código chega como um evento de webhook activation.sms_received, ou você consulta GET /api/v1/activations/{id} por polling.
6. Se o teste for abandonado, POST /api/v1/activations/{id}/cancel reembolsa na hora.

Uma conta suporta 10 chaves de API, 5 endpoints de webhook e 300 requisições por minuto. O guia de integração da API cobre novas tentativas e timeouts.

Como o handler de webhook deve tratar os eventos do Truecaller?

Cada entrega traz X-OTPRoute-Signature: t=<unix>,v1=<hex>. Recalcule o HMAC-SHA256 sobre o timestamp, um ponto e o corpo bruto da requisição com o segredo do seu endpoint, compare em tempo constante e rejeite timestamps antigos demais.

Use o id da ativação como chave de todo o processamento. Os webhooks podem ser reenviados, então um handler que grava o código duas vezes ou avança um teste duas vezes produzirá resultados instáveis; verifique se a ativação já está marcada como concluída antes de agir. Trate activation.expired e activation.cancelled como estados terminais que dizem ao seu executor de testes para parar de esperar. O polling funciona como alternativa no desenvolvimento local, onde não existe endpoint público.

Por que o Truecaller pede um número de telefone, afinal?

O Truecaller é um app de identificação de chamadas e bloqueio de spam, e o número de telefone é a conta. O cadastro confirma que o usuário controla o número antes de o perfil ser criado, e a verificação se repete quando o app é reinstalado ou levado para um novo dispositivo. Em alguns aparelhos o app pode tentar verificar por chamada em vez de SMS. Um número do OTP Gateway captura apenas SMS, então uma verificação por chamada não produzirá um código na ativação; a janela simplesmente se esgota e a carteira é reembolsada.

Motivos legítimos para as equipes verificarem contas do Truecaller incluem checar como os números de suporte ou de entrega de uma empresa são rotulados para as pessoas de um determinado mercado, QA em apps que integram identificação de chamadas e a equipe de operações que precisa de um perfil de trabalho separado do celular pessoal.

Quais países têm rotas do Truecaller?

O levantamento ao vivo lista rotas do Truecaller em 198 países, entre eles Índia, Paquistão, Bangladesh, Nigéria, Quênia, Egito, Indonésia, Sri Lanka, Nepal, Arábia Saudita, Emirados Árabes Unidos, Brasil, México, África do Sul, Reino Unido e Estados Unidos.

Escolha o país de acordo com o caso de teste. Os rótulos de chamadas, as denúncias de spam e o idioma do app seguem o mercado, então uma verificação de como a sua linha de suporte de Lagos aparece deve usar uma rota da Nigéria, não a que por acaso for mais barata. A disponibilidade muda ao longo do dia; consulte o endpoint de preços antes de cada execução.

Pessoas que não são desenvolvedoras conseguem fazer isso pelo painel?

Sim. Entre na conta, abra o OTP Gateway, escolha o Truecaller e um país, confirme o preço exibido, e o número aparece em um cartão de ativação. Digite-o no Truecaller, peça o código, e ele aparece no mesmo cartão quando o SMS chega. A janela de 20 minutos fica visível no cartão. Se nenhum código chegar, ou se você cancelar, o valor integral volta para a sua carteira automaticamente. As recargas da carteira funcionam por cartão ou USDT/USDC, com uma fatura em PDF por e-mail para cada uma; veja os preços.

Por que um código do Truecaller pode não chegar?

Causas comuns:

• O Truecaller recusou o número porque o trata como virtual. Alguns serviços fazem isso; é por isso que você é reembolsado.
• O app escolheu a verificação por chamada em vez de SMS.
• A rota ficou brevemente congestionada. Tente mais tarde ou com outro país que sirva ao seu teste.
• O número foi digitado sem o código do país, ou com um 0 de tronco sobrando.

Não martele o endpoint de pedidos em loop. Espace as tentativas e registre cada id de ativação para enxergar padrões.

Quando um Número Dedicado faz mais sentido para o Truecaller?

Um número de uso único some depois da ativação. Se um perfil do Truecaller precisa ser verificado de novo mais tarde, por exemplo o aparelho de trabalho de uma equipe de suporte que é redefinido, use um Número Dedicado. Eles estão disponíveis de forma instantânea nos Estados Unidos e no Canadá a partir de $1.95/month, recebem SMS no painel e pelo webhook number.sms_received e renovam a partir da carteira até você liberá-los. Veja números virtuais.

Use o OTP Route apenas para suas próprias contas e produtos legítimos: uma conta por pessoa real ou empresa, nenhuma denúncia ou alteração de rótulo contra números de outras pessoas e pleno respeito aos termos do Truecaller e à Política de Uso Aceitável do OTP Route. Truecaller é marca registrada de seu titular, e o OTP Route não é afiliado a ela.

Perguntas frequentes

Qual é o id de serviço do Truecaller na API?

É truecaller. Combine-o com um id de país em GET /api/v1/prices e no corpo de POST /api/v1/activations.

Posso receber um OTP do Truecaller em um número virtual?

Muitas vezes, mas nem sempre; o Truecaller pode recusar números que classifica como virtuais. Se nenhum código chegar em 20 minutos, o valor é reembolsado automaticamente.

Por que o Truecaller ligou em vez de enviar um SMS?

O app pode escolher a verificação por chamada em alguns dispositivos. Os números do OTP Gateway capturam apenas SMS, então peça a opção de SMS se o app a oferecer.

Qual país devo escolher para testar a verificação por SMS do Truecaller?

Escolha o mercado de que o seu teste trata, já que os rótulos de chamadas e o idioma seguem o país do número. Verifique antes a disponibilidade atual no endpoint de preços.

Posso manter o mesmo número de telefone do Truecaller para logins futuros?

Sim, com um Número Dedicado nos Estados Unidos ou no Canadá a partir de $1.95/month. Os números de uso único do Gateway não podem ser reutilizados.

Como evito que entregas duplicadas de webhook quebrem meus testes?

Torne o handler idempotente pelo id da ativação e verifique a assinatura antes de fazer qualquer coisa com o payload.

O OTP Route é afiliado ao Truecaller?

Não. Truecaller é marca registrada de seu titular; o OTP Route fornece números para testar e operar suas próprias contas legítimas.

Os nomes dos serviços são marcas registradas de seus respectivos proprietários. A OTP Route não é afiliada a eles. Use os números de forma lícita e siga os termos de cada serviço e nossa Política de Uso Aceitável.