Как читать ошибку
Для недоставленного сообщения указываются две вещи: исходный код, который вернул оператор связи, и понятная причина, к которой мы этот код относим. Исходные коды у разных операторов различаются, а причина везде одна и та же, поэтому по ней можно действовать. Панель группирует ошибки по причинам и показывает рядом с каждой исходный код, выгрузки содержат код оператора для каждого сообщения, а объект сообщения в API хранит оба значения — failure_reason и carrier_code — вместе с временными метками created_at и sent_at. Ваша система узнаёт о каждой ошибке в момент её возникновения через вебхук message.failed.
Сообщения с ошибкой были переданы оператору связи, который не смог их доставить, поэтому оплачиваются, как любая попытка; сообщения, которые мы отклоняем до отправки, получают статус Отклонено и никогда не оплачиваются. Записи по отдельным сообщениям хранятся 90 дней, а сводки по кампаниям — бессрочно, поэтому выгружайте подробные данные, если хотите сравнивать ошибки за более длительный период.
Где может остановиться сообщение
В каждый момент сообщение находится в одном из нескольких состояний, и разница между ними определяет, что вы платите и что делаете дальше. Полные определения приведены в справочнике API.
| Статус | Что он означает | Оплата |
|---|---|---|
| В очереди (queued) | Принято и ждёт времени отправки, окна или своей очереди | Пока нет |
| Отклонено (rejected) | Не допущено к отправке, например из-за неверного номера или содержания, остановленного фильтрами | Никогда |
| Отправлено (sent) | Передано оператору связи | Да, в этот момент |
| Доставлено (delivered) | Телефон подтвердил получение | Уже оплачено при отправке |
| Ошибка (failed) | Оператор не смог доставить сообщение; указаны причина и код | Да, сообщение было отправлено |
| Срок истёк (expired) | Срок действия закончился до доставки | Да, один раз |
| Тест (test) | Принято с тестовым ключом: проверено и оценено, но не отправлено | Никогда |
Двенадцать причин
- Неизвестный номер. Номер никому не присвоен: введён с ошибкой, никогда не выдавался или закрыт. Удалите его: на него сообщение никогда не будет доставлено. Отчёт удаляет все неизвестные номера из списка одним нажатием.
- Абонент недоступен. Телефон был выключен или вне зоны покрытия и оставался недоступным, пока сеть пыталась доставить сообщение в течение срока действия — по умолчанию 48 часов. Повторите попытку в одной из следующих кампаний.
- Ошибка телефона или память заполнена. Телефон отклонил сообщение, обычно из-за нехватки памяти. На современных телефонах это редкость; повторите попытку позже.
- Заблокировано фильтром оператора. Оператор пометил содержание или отправителя. Проверьте правило отправителя для направления, не используйте сервисы сокращения ссылок на строгих маршрутах и перечитайте текст на предмет фишинговой лексики.
- Портированный номер. Номер перешёл к другому оператору, а сообщение ушло прежнему. Данные о переносе номеров со временем обновляются; повторная попытка обычно проходит успешно.
- Недоступен в роуминге. Абонент находится за границей в сети, которая не принимает сообщение. Повторите попытку позже или смиритесь с потерей.
- Обслуживание абонента приостановлено. Линия заблокирована, часто из-за неоплаченных счетов. Удалите номер после двух таких случаев.
- Реестр «Не беспокоить». На рынках с национальным реестром, например в Индии и Нигерии, рекламный трафик на внесённые в него номера блокируется. Транзакционный трафик проходит, маркетинговый — нет.
- Недопустимый отправитель для маршрута. Оператор отклонил самого отправителя. Это бывает редко, потому что, когда оператор отклоняет имя, сообщение уходит с числового отправителя, и отчёт это отражает. Если вы видите эту причину, сравните отправителя с правилом на странице страны.
- Срок истёк. Срок действия закончился, пока оператор продолжал попытки доставки. В отчёте такое сообщение получает статус «Срок истёк», а не «Ошибка», и повторно не оплачивается. Короткий срок действия, подходящий для кодов, по замыслу делает такой исход более частым.
- Направление недоступно. Проблема на уровне всего оператора; обычно она видна на странице статуса. Дождитесь закрытия инцидента, прежде чем отправлять повторно.
- Отклонено оператором без указания причины. Некоторые операторы возвращают один общий код на все случаи. Маршруты ежедневно пересматриваются по измеренной доставляемости; если код постоянно появляется у одного оператора, отправьте в поддержку несколько идентификаторов сообщений.
Удалить, повторить или изменить
Двенадцать причин сводятся к трём действиям.
- Удаляйте неизвестные номера сразу, а номера с приостановленным обслуживанием — после второго случая. Повторная отправка на них приносит лишь новые ошибки.
- Повторяйте позже для недоступных абонентов, переполненных телефонов, роуминга, портированных номеров, сообщений с истёкшим сроком и сбоев у операторов. Сеть обычно уже повторяла попытки, поэтому немедленная повторная отправка редко помогает; включите эти номера в следующую кампанию или, если сообщение важно, отправьте его повторно через несколько часов.
- Меняйте что-нибудь при блокировках фильтром, ошибках из-за реестра «Не беспокоить» и недопустимых отправителях. Тот же текст от того же отправителя на те же номера завершится той же ошибкой: смените отправителя, формулировку или аудиторию. Переименование акции в транзакционное сообщение — не решение: это считается злоупотреблением.
Любая повторная отправка — это новое сообщение, которое снова оплачивается, как только доходит до оператора связи. Это не то же самое, что повтор API-запроса, завершившегося по тайм-ауту: повторите его с тем же Idempotency-Key, и вы получите исходный результат вместо второго сообщения.
Обработка ошибок в коде
Если вы отправляете через API, пусть вашими действиями управляет вебхук, а не опрос. Указывайте собственный идентификатор в reference — до 128 символов, он возвращается в ответах и вебхуках, — чтобы каждое событие message.failed сразу сопоставлялось с пользователем или заказом. Затем ветвите логику по понятной причине, а не по исходному коду, который различается у разных операторов:
- Неизвестный номер при регистрации или отправке кода: попросите пользователя проверить введённый номер, а не предлагайте повторную отправку.
- Временная причина у срочного сообщения: предложите одну повторную отправку после паузы и ограничьте число попыток.
- Блокировка фильтром: оповестите человека. Автоматические повторные отправки того же текста лишь повторяют блокировку, и каждая из них оплачивается.
Всё равно сохраняйте carrier_code вместе с событием. Именно он нужен поддержке, чтобы отследить закономерность у одного оператора.
На какие закономерности реагировать
Одна ошибка — шум, доля — сигнал. Анализируйте ошибки по причинам, затем по направлениям и операторам, затем в сравнении с предыдущей отправкой по тому же списку.
- Растущая доля неизвестных номеров означает, что список устаревает. Очистите его из отчёта одним нажатием, а затем выясните, откуда взялись эти номера.
- Растущая доля блокировок фильтром у одного оператора означает, что там помечают содержание или отправителя: смените тип отправителя или уберите сокращённую ссылку и снова проверьте на телефоне в этой сети.
- Ошибки, сосредоточенные в одном импорте, указывают на его источник: форму без проверки, список партнёра, старую выгрузку.
- Резкий скачок у всех операторов одной страны — это проблема маршрута, и решать её нам: она появится на странице статуса, обычно ещё до того, как вы её заметите.
Быстрый способ просмотреть весь отчёт описан в статье о том, как прочитать отчёт о доставке за две минуты.
Как предотвратить устранимые ошибки
Часть ошибок можно остановить ещё до отправки, где они ничего не стоят.
- Очищайте файл при импорте. Импортёр приводит номера к формату E.164, объединяет дубликаты и перечисляет неверные строки, которые никогда не отправляются и не оплачиваются. Укажите страну по умолчанию, если в файле местные форматы; остальное описано в руководстве по подготовке списка контактов.
- Подбирайте отправителя под направление. Руководство по идентификаторам отправителя объясняет три правила и то, что каждое из них показывает на телефоне.
- Пишите с учётом фильтров. Бренд в первых словах, ссылки на собственном домене, никакой нагнетаемой срочности, ничего, что имитирует банк или оператора связи.
- Задавайте срок действия по времени, пока сообщение полезно. Десять минут для кода, потому что код, доставленный после истечения срока, — это обращение в поддержку; стандартные 48 часов для кампании.
- Интегрируйтесь с тестовым ключом. Он проверяет запросы и рассчитывает цену так же, как рабочий ключ, поэтому неправильно оформленные номера обнаруживаются до того, как что-либо будет отправлено или оплачено.
Что не считается ошибкой
Отправлено без Доставлено — не ошибка. Большинство направлений возвращают подтверждения с телефона, но некоторые дают только подтверждение оператора связи, и там Отправлено — окончательный положительный статус; кроме того, некоторые операторы возвращают отчёты с опозданием или пакетами. Что действует в конкретном направлении, указано на странице страны, а как читать подтверждения, объясняет страница отчётов о доставке. Доставлено означает, что сообщение есть на телефоне, но не что его кто-то прочитал. В очереди означает ожидание окна или времени отправки, как и задумано. И Отклонено — тоже не ошибка: это платформа отказывается отправлять то, что завершилось бы ошибкой, и отказывается за это списывать средства.
Что-то непонятно или устарело? Сообщите нам на странице поддержки. Мы внесём исправления в руководство и обновим дату.
