Программный приём SMS-кодов Truecaller

Как выглядит цепочка вызовов API для Truecaller?

Id сервиса Truecaller — truecaller, и все вызовы ниже выполняются к https://otproute.com/api/v1 с Bearer-ключом, префикс которого or_live_.

1. GET /api/v1/countries отдаёт id стран; кэшируйте их.
2. GET /api/v1/prices?country=<id>&service=truecaller возвращает актуальную цену и показывает, открыт ли сейчас маршрут.
3. POST /api/v1/activations с {"service": "truecaller", "country": "in"} (или с id любой другой страны) резервирует номер и возвращает id активации.
4. Введите этот номер в приложении Truecaller на тестовом устройстве и запросите верификацию.
5. Код приходит событием вебхука activation.sms_received, либо вы опрашиваете GET /api/v1/activations/{id}.
6. Если тест прерван, POST /api/v1/activations/{id}/cancel немедленно возвращает средства.

Аккаунт поддерживает 10 API-ключей, 5 эндпоинтов вебхуков и 300 запросов в минуту. О повторах и тайм-аутах рассказывает руководство по интеграции OTP API.

Как обработчик вебхука должен работать с событиями Truecaller?

Каждая доставка несёт X-OTPRoute-Signature: t=<unix>,v1=<hex>. Заново вычислите HMAC-SHA256 от метки времени, точки и сырого тела запроса с секретом вашего эндпоинта, сравните за постоянное время и отклоняйте слишком старые метки времени.

Строить всю обработку нужно вокруг id активации. Вебхуки могут повторяться, поэтому обработчик, который дважды сохранит код или дважды продвинет тест, даст нестабильные результаты; перед действием проверяйте, не помечена ли активация уже как завершённая. Считайте activation.expired и activation.cancelled конечными состояниями, которые сообщают вашему тестовому раннеру, что ждать больше не нужно. Опрос работает как запасной вариант для локальной разработки, где нет публичного эндпоинта.

Зачем Truecaller вообще запрашивает номер телефона?

Truecaller — приложение определителя номера и блокировки спама, и номер телефона в нём и есть аккаунт. Регистрация подтверждает, что пользователь владеет номером, прежде чем будет создан профиль, а проверка повторяется при переустановке приложения или переносе на новое устройство. На некоторых устройствах приложение может пытаться подтвердить номер звонком, а не SMS. Номер OTP Gateway принимает только SMS, поэтому проверка звонком не даст кода в активации; окно просто истечёт, и кошелёк получит возврат.

Законные причины проверять аккаунты Truecaller у команд такие: посмотреть, как подписываются исходящие номера поддержки или доставки компании для людей на определённом рынке, QA приложений, интегрирующих определение звонящего, и сотрудники операционных отделов, которым нужен рабочий профиль отдельно от личного телефона.

В каких странах есть маршруты Truecaller?

Актуальный снимок показывает маршруты Truecaller в 198 странах, среди них Индия, Пакистан, Бангладеш, Нигерия, Кения, Египет, Индонезия, Шри-Ланка, Непал, Саудовская Аравия, ОАЭ, Бразилия, Мексика, Южная Африка, Великобритания и США.

Выбирайте страну под тестовый сценарий. Метки звонящих, жалобы на спам и язык приложения зависят от рынка, поэтому проверка того, как отображается ваша линия поддержки в Лагосе, должна идти по нигерийскому маршруту, а не по тому, который случайно дешевле. Наличие меняется в течение дня; запрашивайте эндпоинт цен перед каждым прогоном.

Могут ли не разработчики сделать это из панели?

Да. Войдите, откройте OTP Gateway, выберите Truecaller и страну, подтвердите показанную цену, и номер появится на карточке активации. Введите его в Truecaller, запросите код, и он появится на той же карточке, когда придёт SMS. 20-минутное окно видно на карточке. Если код не пришёл или вы отменили заказ, вся сумма автоматически возвращается на кошелёк. Кошелёк пополняется картой или USDT/USDC, и на каждое пополнение по почте приходит PDF-счёт; см. цены.

Почему код Truecaller может не прийти?

Частые причины:

• Truecaller отклонил номер, посчитав его виртуальным. Так делают некоторые сервисы; именно поэтому предусмотрен возврат.
• Приложение выбрало верификацию звонком вместо SMS.
• Маршрут был ненадолго перегружен. Повторите позже или с другой страной, которая подходит вашему тесту.
• Номер введён без кода страны или с лишним транковым 0.

Не долбите эндпоинт заказа в цикле. Разносите попытки по времени и записывайте id каждой активации, чтобы видеть закономерности.

Когда для Truecaller больше подходит выделенный номер?

Одноразовый номер исчезает после активации. Если профиль Truecaller придётся верифицировать повторно, например на рабочем устройстве команды поддержки, которое сбросили, используйте выделенный номер. Они доступны мгновенно в США и Канаде от $1.95/month, принимают SMS в панели и через вебхук number.sms_received и продлеваются с кошелька, пока вы их не освободите. См. виртуальные номера.

Используйте OTP Route только для собственных законных аккаунтов и продуктов: один аккаунт на реального человека или компанию, никаких жалоб и смены меток в отношении чужих номеров и полное соблюдение условий Truecaller и Политики допустимого использования OTP Route. Truecaller — товарный знак его владельца, и OTP Route не связан с ним.

Частые вопросы

Какой id сервиса у Truecaller в API?

truecaller. Указывайте его вместе с id страны в GET /api/v1/prices и в теле POST /api/v1/activations.

Можно ли получить OTP Truecaller на виртуальный номер?

Часто да, но не всегда; Truecaller может отклонять номера, которые считает виртуальными. Если код не пришёл за 20 минут, оплата возвращается автоматически.

Почему Truecaller позвонил вместо отправки SMS?

На некоторых устройствах приложение может выбрать верификацию звонком. Номера OTP Gateway принимают только SMS, поэтому выбирайте вариант SMS, если приложение его предлагает.

Какую страну выбрать для тестирования SMS-верификации Truecaller?

Ту, о которой ваш тест, поскольку метки звонящих и язык зависят от страны номера. Сначала проверьте актуальное наличие через эндпоинт цен.

Можно ли сохранить тот же номер Truecaller для последующих входов?

Да, с выделенным номером в США или Канаде от $1.95/month. Одноразовые номера Gateway повторно использовать нельзя.

Как не дать повторным доставкам вебхука ломать мои тесты?

Сделайте обработчик идемпотентным по id активации и проверяйте подпись, прежде чем делать что-либо с данными.

Связан ли OTP Route с Truecaller?

Нет. Truecaller — товарный знак его владельца; OTP Route предоставляет номера для тестирования и работы с вашими законными аккаунтами.

Названия сервисов являются товарными знаками их владельцев. OTP Route не связан с ними. Используйте номера законно, соблюдайте условия каждого сервиса и нашу Политику допустимого использования.