Текст сообщения
Сначала бренд, затем код и больше ничего существенного: ACME: ваш код 493 201. Он действует 10 минут. Ставьте код ближе к началу, чтобы он был виден в превью уведомления, и укладывайте текст в один сегмент GSM-7 длиной 160 символов. Один типографский апостроф, вставленный из макета, переводит всё сообщение в Unicode, где в один сегмент помещается 70 символов. API никогда не изменяет текст, поэтому шаблон должен быть чистым ещё до запуска; типичные виновники перечислены в руководстве по кодировкам. Не добавляйте ссылки: коды со ссылками операторы фильтруют чаще, чем сообщения любого другого вида.
Бренд должен быть в самом тексте, потому что поле отправителя не всегда его покажет. В странах Америки и в Китае любое имя заменяется местным номером; там, где требуется регистрация, до её одобрения используется общий числовой отправитель; а если оператор связи отклоняет имя, такое сообщение уходит с числового отправителя. Эти три случая разобраны в правилах идентификатора отправителя. Буквенно-цифровой отправитель работает только в одну сторону, поэтому никогда не просите ответить на сообщение с кодом.
Два дополнения стоят занимаемых символов. Укажите, для чего нужен код, — для входа или для подтверждения нового устройства — и добавьте Никому не сообщайте этот код: и то и другое помогает человеку заметить, что звонящий пытается выманить у него код. Если при входе на сайт используется автозаполнение, завершите сообщение строкой вида @example.com #493201: Safari и Chrome на Android распознают этот привязанный к домену формат и предлагают код только на этом домене. Приложениям для Android, которые считывают коды через SMS Retriever API, вместо этого нужен 11-символьный хеш приложения в тексте сообщения.
Длина и формат кода
Обычно выбирают шесть цифр, и арифметика объясняет почему. Шесть цифр дают 1 000 000 комбинаций; если код аннулируется после пяти неверных попыток, шанс злоумышленника на один код составляет 5 из 1 000 000, то есть 1 из 200 000. Четыре цифры дают 10 000 комбинаций, и те же пять попыток — шанс 1 из 2000. Восемь цифр удлиняют ввод, почти ничего не добавляя к защите.
- Только цифры. Они открывают цифровую клавиатуру и исключают путаницу между O и 0.
- Криптографически стойкий генератор случайных чисел, но никогда не генератор общего назначения.
- Текст, а не число. Если хранить код как целое число, 042817 превратится в 42817, и правильно введённый код не пройдёт проверку.
- Хеш с секретным ключом в хранилище вместо самого кода; сравнивайте его за постоянное время и привязывайте к одному номеру и одной цели.
- Пробел для удобства чтения, как в 493 201, помогает тем, кто вводит код вручную; если вы полагаетесь на автозаполнение, проверьте точный формат на реальных устройствах.
# Python. В Node: crypto.randomInt(0, 1000000).toString().padStart(6, "0")
import secrets
code = f"{secrets.randbelow(1_000_000):06d}" # "042817" сохраняет ведущий нольСрок действия
Код живёт несколько минут, обычно от пяти до десяти. Задайте в сообщении поле validity (в минутах) равным этому сроку, а не оставляйте значение по умолчанию 2880 (48 часов). Когда телефон выключен или находится вне зоны покрытия, сеть повторяет попытки доставки, пока не истечёт срок действия: при 10 минутах сообщение завершится статусом Срок истёк, а при 48 часах может прийти на следующее утро с уже недействительным кодом. Код, доставленный после истечения срока, — это обращение в поддержку.
Используйте одно и то же значение везде: срок действия на сервере, поле validity и слова в тексте. Если в тексте сказано «десять минут», а сервер принимает код только пять, пользователь, которому понадобилось семь минут, получит отказ не по своей вине.
Настройки API
Запросу кода к POST /v1/messages помимо номера и текста нужно ещё несколько настроек:
POST /v1/messages
Authorization: Bearer sk_live_...
Idempotency-Key: verify-8812-attempt-2
Content-Type: application/json
{
"to": "+447700900123",
"from": "ACME",
"text": "ACME: your code is 493201. It expires in 10 minutes. Never share this code.",
"validity": 10,
"window": { "quiet_hours": "bypass" },
"campaign": "otp-login",
"reference": "verify-8812"
}quiet_hours: bypassпомечает трафик как транзакционный, чтобы он уходил в любое время суток. Используйте этот параметр только для кодов: рекламный контент, помеченный как транзакционный, считается злоупотреблением. Подробнее — в статье об обходе ограничений по времени отправки.Idempotency-Key, составленный из идентификатора проверки и номера попытки, гарантирует, что повтор запроса после сетевой ошибки на вашей стороне вернёт исходный результат, а не отправит второй код. Намеренная повторная отправка — это новая попытка с новым ключом.campaignгруппирует трафик кодов в отчётах, аreferenceвозвращается в ответах и вебхуках — так событие доставки находит свою проверку.
Проверяйте encoding и segments в ответе: если шаблон кода возвращается с ucs2 или двумя сегментами, в нём есть лишний символ. Выделите сервису кодов отдельный ключ только с правом отправки; ограничение в 50 запросов в секунду действует для каждого ключа отдельно, поэтому массовая задача на другом ключе не израсходует лимит, необходимый вашим кодам. Интеграционные тесты выполняйте на тестовом ключе: он проверяет запросы, рассчитывает цену и отвечает как рабочий ключ, а также вызывает подписанные вебхуки, но ничего не отправляет и не списывает.
Интервалы повторной отправки
Разрешайте запросить новый код через 30 секунд, затем через 60, затем через 120, с видимым обратным отсчётом. При выпуске нового кода аннулируйте предыдущий, чтобы принимался только последний, и ограничьте общее количество: трёх-четырёх кодов на номер в час реальному человеку вполне достаточно. Показывайте номер, на который ушёл код, частично скрытым, а рядом с кнопкой повторной отправки дайте возможность его исправить. Опечатка в номере означает код, который не придёт, и никакая повторная отправка этого не исправит.
Прежде чем предлагать ещё одну попытку, проверьте статус. Сообщение со статусом Отклонено не было допущено к отправке и не оплачивалось; если ошибка связана с номером, попросите ввести его заново. Событие message.failed с причиной «неизвестный номер» означает то же самое: предложите пользователю проверить номер, а не отправить код ещё раз. Статус Отправлено без Доставлено — не ошибка в направлениях, которые возвращают только подтверждение оператора связи; какие это направления, указано на странице страны. Обработчик, который принимает эти события, описан в руководстве по вебхукам в рабочей среде.
Если SMS не приходит
Для каждого направления используется один маршрут, выбранный по измеренной доставляемости, поэтому второе SMS идёт тем же путём, что и первое. Это помогает, если первое потерялось из-за временной проблемы. Но не помогает, если телефон выключен, находится в роуминге в сети, которая отклоняет сообщение, или номер указан неверно. Начиная со второго кода предлагайте рядом с кнопкой повторной отправки другой канал, а после ошибки, которую повторная отправка не исправит, сразу переключайтесь на него:
- Электронная почта на адрес, уже подтверждённый в аккаунте.
- Приложение-аутентификатор или ключ доступа (passkey), предложенные при настройке входа, чтобы они появились ещё до того, как SMS подведёт.
- Голосовой звонок, в котором зачитывается код, через того провайдера, которого вы используете для голосовой связи.
- Резервные коды, выданные при регистрации, для восстановления доступа к аккаунту.
Применяйте к резервному каналу те же ограничения, что и к SMS: незащищённым голосовым каналом можно злоупотребить точно так же.
Ограничения частоты и SMS pumping
Конечная точка выдачи кодов без ограничений — это способ потратить ваш баланс. У этой атаки несколько названий (SMS pumping, toll fraud, искусственно накрученный трафик): скрипт запрашивает коды для тысяч номеров в диапазонах, где кто-то в цепочке получает долю платы за терминацию. Все номера действительны, поэтому каждое сообщение отправляется и оплачивается; бесплатны только сообщения, отклонённые до отправки, со статусом Отклонено. Ограничения на номер телефона такую атаку не останавливают, потому что в каждом запросе используется другой номер. Предоплаченный баланс ограничивает ущерб, но этот предел — весь баланс, включая средства, нужные для завтрашней кампании.
| Ограничение | Пример начального значения | Что оно останавливает |
|---|---|---|
| На номер телефона | 4 кода в час, 10 в сутки | Зацикленные запросы и преследование одного человека |
| На IP-адрес | 10 кодов в час, так как мобильные сети используют общие адреса | Простые скрипты |
| На аккаунт или сессию | 5 кодов в час | Злоупотребления из авторизованных сессий |
| На страну и диапазон префиксов | Почасовой потолок чуть выше вашего обычного пика | SMS pumping, распределённый по множеству номеров |
| Глобальное | Почасовой потолок расходов с вызовом дежурного | Всё, что пропустили остальные ограничения |
Подберите значения под свой трафик: структура важнее конкретных чисел. Затем добавьте недорогие меры защиты: отклоняйте направления, которые вы не обслуживаете, ещё до вызова API, требуйте пройти проверку после второго запроса, проверяйте формат номера на своей стороне и отвечайте одинаково независимо от того, есть ли у номера аккаунт, чтобы через конечную точку нельзя было выяснить, какие номера зарегистрированы. Тревожные признаки — всплеск трафика в страну, куда вы редко отправляете, номера, идущие подряд или с длинным общим префиксом, и коды, которые отправляются, но почти никогда не вводятся.
Что измерять
Конверсию из отправленного кода во введённый по каждому направлению. Это лучший показатель доставки, чем любой отчёт о доставке, потому что он учитывает телефон, уведомление и самого пользователя, а в направлениях, которые возвращают только подтверждение оператора связи, это единственный сквозной сигнал, который у вас есть. Свяжите записи о проверках с событиями сообщений через reference и отслеживайте:
- Конверсию по направлению и по попытке: код введён после первого сообщения, после второго или не введён вовсе.
- Время проверки от запроса до правильного ввода: смотрите на самую медленную десятую часть, а не только на медиану.
- Долю повторных отправок: её рост в одном направлении заслуживает отдельного оповещения.
- Стоимость одного подтверждённого пользователя: расходы, делённые на число завершённых проверок.
Допустим, в одно направление за неделю отправлено 2000 кодов на сумму 60, и проверку завершили 1500 человек: конверсия составляет 75%, а каждый подтверждённый пользователь обходится в 0,04. Направление, где конверсия на десять процентных пунктов ниже, чем в остальных, заслуживает проверки правила отправителя и причин ошибок; резкое падение конверсии при растущем объёме — это SMS pumping, пока не доказано обратное. Выгрузки в CSV или JSON содержат идентификатор, статус, код оператора, временные метки и цену каждого сообщения; эти данные хранятся 90 дней. См. также сценарий проверки с помощью OTP.
Что-то непонятно или устарело? Сообщите нам на странице поддержки. Мы внесём исправления в руководство и обновим дату.
