Как выбрать API для обмена сообщениями: чек-лист для CTO

Этот чек-лист предназначен для CTO, технических руководителей и архитекторов, которые выбирают API для сообщений в SMS, WhatsApp, RCS и других каналах. Он превращает расплывчатое сравнение поставщиков в конкретные вопросы, тесты, которые можно выполнить за полдня, и таблицу оценок, которую не стыдно показать финансовому отделу и службе безопасности.

Если вы уже выбрали провайдера и вам нужно построить интеграцию, прочитайте наше руководство по интеграции API для сообщений. Эта статья посвящена решению, которое предшествует интеграции.

Что CTO нужно оценить в API для сообщений?

Оценивайте то, что влияет на результат в рабочей среде: доходят ли сообщения, видно ли, что произошло, переживает ли интеграция сбои и соблюдаются ли требования. Списки функций у провайдеров похожи, а эти свойства различаются.

Покрывает ли API нужные вам каналы?

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

• Составьте список каналов на ближайшие два года, а не только на сегодня. Команды, которые начинают с SMS OTP, часто добавляют шаблоны WhatsApp, затем RCS, затем email или push.
• Проверьте глубину поддержки канала, а не только логотип. Для WhatsApp: можно ли через API управлять шаблонами, отправлять интерактивные сообщения и отслеживать одобрение? Для SMS: доступны ли двусторонний обмен, Unicode и проверка номеров?
• Проверьте резервный канал (fallback). Если сообщение в WhatsApp не доставлено, может ли платформа переключиться на RCS или SMS и настраивается ли порядок для каждого сценария? Наше сравнение WhatsApp, SMS и RCS объясняет, когда подходит каждый канал.

Как оценить качество маршрутов?

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

Прямой маршрут означает, что провайдер подключён к оператору или его уполномоченному партнёру по соглашению, которое охватывает A2P-трафик (от приложения к человеку). Серый маршрут пропускает A2P-трафик по путям, не предназначенным для этого, например через потребительские SIM-карты. В прайс-листе серые маршруты могут выглядеть дешевле, но риски у них реальные:

• имя отправителя заменяется случайным номером, что подрывает доверие и привычку к автозаполнению OTP-кодов;
• операторы обнаруживают и блокируют такой трафик, иногда посреди кампании;
• отчёты о доставке могут формироваться самим маршрутом, а не сетью, поэтому «доставлено» не всегда означает доставлено.

Вопросы, которые нужно задать:

1. До каких операторов в наших странах назначения вы подключены напрямую?
2. Как вы организуете регистрацию имени отправителя в каждой стране?
3. Откуда приходят ваши отчёты о доставке и передаёте ли вы код ошибки оператора?
4. Что происходит с нашим трафиком, когда маршрут деградирует? Переключение автоматическое и сообщаете ли вы нам об этом?

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

Как устроены отчёты о доставке и вебхуки?

Провайдер должен отправлять статусы доставки на ваш HTTPS-адрес в едином нормализованном формате для всех каналов и давать возможность восстановить пропущенные события. Опрашивать каждое сообщение — неустойчивая архитектура.

Как выглядит хороший вариант:

• Документированный список статусов. Например, SUBMITTED, SENT, DELIVERED, READ, FAILED и REJECTED с указанием, какие из них финальные. Наше руководство по статусам доставки объясняет, что означает каждый на практике.
• Причины сбоев. Статус FAILED или REJECTED должен содержать причину от оператора или канала, если она есть.
• Восстановление. Если ваш адрес был недоступен, можно ли запросить повторную отправку отчётов за период или прочитать статус по каждому получателю?
• Честные рекомендации о порядке и дублях. События могут приходить не по порядку и более одного раза. Документация, которая прямо об этом говорит, заслуживает больше доверия, чем та, что это игнорирует.
• Защита адреса. Спросите, подписываются ли вебхуки. Если нет, провайдер должен объяснить, как защитить адрес: например, только HTTPS, неугадываемый путь, строгая проверка тела запроса и подтверждение состояния перед необратимыми действиями.

Какой уровень аутентификации и безопасности ожидать?

Как минимум: токены передаются в заголовке Authorization по TLS и никогда в URL; есть понятный процесс ротации и отзыва учётных данных; меры безопасности проходят независимый аудит. Bearer-токены определены в RFC 6750, а список OWASP API Security Top 10 удобно пройти вместе с поставщиком.

Спросите:

• Как токены выдаются, ограничиваются по правам и отзываются? Можно ли иметь отдельные токены для каждого сервиса или среды? Как быстро отзывается утёкший токен?
• Передаются ли учётные данные в параметрах URL? Некоторые устаревшие HTTP API до сих пор принимают логин и пароль в строке запроса, откуда они попадают в журналы. Для новых интеграций этого лучше избегать.
• Доступен ли список разрешённых IP-адресов и где? Он обычен для SMPP-подключений; уточните, работает ли он и для REST.
• Какие сертификаты распространяются на сервис? Запросите сам сертификат или отчёт, а не только логотип, и проверьте область действия.
• Где хранится содержимое сообщений и как долго? Это важно для проверок по защите данных.

На какие лимиты и пропускную способность рассчитывать?

Ожидайте документированные лимиты по умолчанию, ответ 429 Too Many Requests (RFC 6585) с заголовком Retry-After при их превышении и процесс согласования более высоких потолков для пиков в продакшене. Недокументированные лимиты обнаруживаются во время вашей самой крупной кампании.

• Запросите лимиты по каждому интерфейсу: у REST-запросов, SMPP-подключений и вызовов проверки номеров часто отдельные лимиты.
• Проверьте массовые эндпоинты. Один запрос с файлом получателей нагружает лимиты меньше, чем тысячи одиночных запросов.
• Узнайте, как обрабатываются пики. Распродажи и аварийные оповещения нужно планировать вместе с провайдером, а не надеяться на удачу.
• Продумайте свою сторону. Очередь и ограничитель по схеме token bucket перед API удерживают несколько воркеров в пределах вашей квоты.

Наш справочник по ошибкам и лимитам показывает, как выглядит такая документация на практике.

Насколько хороши SDK и документация?

Хорошая документация позволяет инженеру отправить реальное сообщение, получить статус и обработать ошибку без обращения в поддержку. Запросите документ OpenAPI: провайдер, который его поддерживает, может дать вам сгенерированные клиенты, коллекции Postman и точные названия полей.

Признаки качества:

• спецификация OpenAPI 3.x, которая соответствует действующему API;
• хотя бы один поддерживаемый SDK и примеры на чистом HTTP для других языков;
• точные названия полей запроса, документированное тело ошибки с машиночитаемым кодом и примеры ответов;
• быстрый старт, который заканчивается статусом доставки, а не просто «200 OK»;
• честные примечания о том, что не поддерживается.

Как API обрабатывает повторные запросы и дубли?

Запрос на отправку может успешно выполниться на сервере, а ответ при этом потеряться, и тогда слепой повтор отправит клиенту одно и то же сообщение дважды. Спросите, как провайдер предлагает этого избегать.

Некоторые API принимают ключ идемпотентности: вы отправляете с запросом уникальное значение, а повторный запрос с тем же значением возвращает исходный результат. Другие, включая наш, его не принимают; тогда документированный подход такой: записать каждую отправку в вашу базу данных до её выполнения, сохранить возвращённый идентификатор сообщения, а после тайм-аута проверить, есть ли признаки того, что запрос принят, прежде чем отправлять повторно. Подойдёт любой вариант, если он задокументирован. Не подойдёт провайдер, который об этом не задумывался. Страница об ошибках и лимитах показывает схему «записать до отправки».

Есть ли безопасный тестовый доступ?

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

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

Нужна ли опция SMPP?

Скорее всего, не в первый день, но позже может понадобиться. SMPP v3.4 — телеком-протокол обмена SMS по постоянному соединению; он подходит для больших и стабильных объёмов SMS, агрегаторов и реселлеров. Спросите, предлагает ли провайдер SMPP поверх TLS, как выдаются bind-доступы и используются ли те же маршруты, что и для REST. Наше сравнение SMS API и SMPP подробно разбирает оба варианта.

Могут ли ИИ-агенты безопасно пользоваться API?

Если ваши команды используют ИИ-ассистентов или создают агентов, MCP-сервер (Model Context Protocol) позволяет им находить и вызывать инструменты для сообщений без собственного связующего кода. Узнайте, что агент может делать и с какими правами.

Вопросы, которые нужно задать:

• Действует ли MCP-сервер с теми же токеном и правами, что и наш собственный код?
• Можно ли включить только нужные агенту инструменты, например отчёты о доставке без инструментов отправки?
• Доступны ли временные ключи для экспериментов?
• Будут ли отправки видны в тех же отчётах о доставке, чтобы мы могли проверять поведение агента?

Пример таких средств контроля смотрите в нашей документации MCP-сервера.

Какую поддержку комплаенса должен предоставлять провайдер?

Провайдер должен помогать регистрировать имена отправителей там, где это требуется, поддерживать обработку отписок (opt-out) и обрабатывать данные в рамках признанных мер безопасности и защиты приватности. Ответственность за согласие на получение сообщений (opt-in) остаётся на вас, но провайдер должен сделать его получение практичным.

• Имена отправителей: в некоторых странах требуется регистрация альфа-имён, а в некоторых — регуляторные идентификаторы в каждом сообщении. См. наше руководство по регистрации имени отправителя в ОАЭ и Саудовской Аравии.
• Согласие: спросите, как фиксируются отписки при двусторонней SMS-переписке и как они попадают в ваши системы. Наше руководство по согласию описывает обязательства.
• Защита данных: уточните соглашения об обработке данных, место размещения, сроки хранения и субобработчиков.

О чём спросить про поддержку и SLA?

Считайте условия поддержки частью продукта и фиксируйте их письменно. Не сравнивайте громкие цифры из рекламных материалов; сравнивайте то, что закреплено в договоре.

• Как инциденты обнаруживаются, как о них сообщают и как их закрывают?
• В какие часы, часовые пояса и на каких языках работает поддержка?
• Кто решает проблемы на стороне оператора, например имя отправителя, заблокированное в одной стране?
• Есть ли персональный контакт или инженер по внедрению на время интеграции?
• Какие обязательства закреплены в соглашении, как они измеряются и что происходит при их нарушении?

Насколько прозрачны цены?

Вы должны иметь возможность оценить ежемесячный счёт по опубликованному прайс-листу и своим объёмам. Спросите:

• Цена указана за сообщение, за сегмент или за доставленное сообщение и отличается ли это по каналам?
• Какие сторонние сборы выставляются отдельно, например тарифы Meta за WhatsApp?
• Оплата предоплатная или постоплатная и что будет, если баланс закончится посреди кампании?
• Тарифицируются ли отдельно проверка номеров, регистрация имени отправителя и выделенные SMPP-подключения?

Помните, что сообщения в Unicode и длинные сообщения занимают больше SMS-сегментов. Наше руководство по ограничениям длины объясняет, почему кампания на арабском может стоить дороже, чем на английском.

Как оценивать провайдеров?

Проведите один и тот же практический тест у каждого провайдера из короткого списка, а затем оцените их в одной таблице. Расставьте веса критериев по собственным приоритетам; приведённые ниже веса — отправная точка, а не стандарт.

Порядок оценки

1. Составьте короткий список из двух-четырёх провайдеров, которые покрывают ваши каналы и страны.
2. Запросите у каждого тестовый доступ и отметьте, сколько времени это заняло.
3. Проведите у каждого провайдера приведённый ниже быстрый тест.
4. Отправьте сообщения на реальные телефоны каждого крупного оператора в ваших основных странах.
5. Задайте письменные вопросы из каждого раздела выше.
6. Оцените каждый критерий от 1 до 5, умножьте на вес и сложите результаты.
7. Обсудите двух лидеров со службой безопасности, финансовым отделом и командой, которая будет эксплуатировать интеграцию.

Быстрый тест

Документация каждого провайдера должна позволять сделать нечто подобное. Вот эквивалентный вызов нашего API, как показано в кратком руководстве:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "OmniDemo",
    "destinationNumber": "447700900123",
    "message": "Your OmniDemo code is 482913",
    "messageType": "TEXT"
  }'

Успешный вызов возвращает 200 OK и идентификатор сообщения обычным текстом. Во время теста проверьте ещё четыре вещи: что происходит при намеренно неверном токене (ожидайте 401), при некорректном номере (ожидайте 400 с кодом ошибки), при сообщении на арабском (оно должно отправляться в Unicode; см. справочник SMS API) и доходит ли статус DELIVERED до вашего вебхука.

Рабочий пример: финтех выбирает провайдера для OTP и уведомлений

«Nakheel Pay» (вымышленный пример) — платёжное приложение в Саудовской Аравии и ОАЭ. Сейчас ему нужны OTP-коды по SMS, а в течение года — уведомления о транзакциях в WhatsApp.

• Короткий список: три провайдера, покрывающие обе страны и оба канала.
• Быстрый тест: у одного провайдера тестовый доступ приходит в течение нескольких дней; другой требует длительного процесса с отделом продаж ещё до любого теста. Это фиксируется в критерии «тестовый доступ».
• Тесты на телефонах: у одного провайдера зарегистрированное имя отправителя отображается у всех проверенных операторов; у другого на одном из операторов показывается числовой отправитель. Провайдеру задают вопрос о маршруте, и он получает низкую оценку по качеству маршрутов.
• Дубли: команда выясняет, как каждый провайдер обрабатывает повторы. Один принимает ключ идемпотентности, другой документирует схему «записать до отправки». Оба варианта приемлемы; команда один раз реализует эту схему в своём сервисе отправки.
• Проверка безопасности: служба безопасности изучает область действия сертификатов и процесс отзыва токенов.
• Решение: взвешенная таблица выбирает провайдера с прямыми маршрутами, нормализованными вебхуками и опцией SMPP на будущее, хотя у другого цена SMS была немного ниже.

Типичные ошибки при выборе API для сообщений

• Выбор только по цене за сообщение. Недоставленные сообщения и заменённые имена отправителей обходятся дороже, чем экономия.
• Тестирование только в имитирующей песочнице. Поведение операторов видно только на реальных телефонах.
• Игнорирование дублей. Цикл повторов без защиты отправляет OTP-коды дважды.
• Отождествление «отправлено» и «доставлено». Узнайте, как передаются итоговые статусы.
• Откладывание проверки безопасности до завершения интеграции, когда смена провайдера обходится дорого.
• Устные обязательства. Условия поддержки и сервиса должны быть в договоре.
• Ограничения этого чек-листа: он описывает хорошую практику и не является юридической консультацией. Уточняйте правила стран у регуляторов и у вашего провайдера.

Как помогает OmniChannels.ai

OmniChannels.ai предоставляет один REST API по адресу https://api.broadnet.me для SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, Email и Push с аутентификацией по Bearer-токену, примерно 330 документированными путями, спецификацией OpenAPI 3.1 и TypeScript SDK @broadnet/cpaas-sdk. Статусы доставки приходят на ваш вебхук в едином формате. Для больших объёмов SMS доступен SMPP 3.4 поверх TLS, а MCP-сервер позволяет ИИ-агентам использовать тот же API. Трафик идёт по прямым подключениям BroadNet к более чем 1 000 операторов и агрегаторов. Тестовый доступ выдаётся на ваши собственные верифицированные номера; начните с обзора для разработчиков.