Документация

Быстрый старт с TextBee

Как подключить телефон, отправить первый SMS через API и настроить переадресацию входящих. Только то, что реально работает сегодня.

01Быстрый старт

  1. Установите приложение — скачайте APK на странице установки, установите на Android 6.0 или новее.
  2. Разрешите доступ к SMS — при первом запуске приложение попросит разрешения на SMS и телефон. Без них шлюз не заработает.
  3. Зарегистрируйтесь в личном кабинете.
  4. Подключите телефон — получите шестизначный код в личном кабинете и введите его в приложении.
  5. Отправьте тестовое SMS прямо из личного кабинета, чтобы убедиться, что всё работает.

02Подключение телефона

Один аккаунт может иметь несколько подключённых телефонов, в пределах лимита вашего тарифа. Каждое подключение — это отдельный шестизначный код, который создаётся в личном кабинете и вводится в приложении при первом запуске (или при добавлении нового телефона).

Если телефон отключился (например, долго не было соединения с интернетом), статус устройства в личном кабинете покажет это, переподключение происходит автоматически, когда телефон снова окажется в сети.

03Отправка SMS через API

Токен доступа (Bearer-токен) вы получаете после входа в личный кабинет. Пример запроса: 

curl https://api.textbee.ru/v1/sms/send \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+79161234567", "text": "Здравствуйте! Ваш код: 12345"}'

Ответ содержит идентификатор сообщения: по нему можно проверить статус доставки через GET /v1/messages/{id}.

Токен из личного кабинета — это сессионный токен для входа, а не отдельный долгоживущий API-ключ. Если вы интегрируете TextBee в постоянно работающий сервис — закладывайте механизм повторного получения токена, а не храните один и тот же токен неограниченно долго.

04Отправка из личного кабинета

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

05Переадресация входящих

В личном кабинете настраивается переадресация входящих SMS. Переадресация бесплатна на всех тарифах, квота тарифа считается только на отправку. Доступные каналы:

  • Push-уведомление (ntfy) — быстрее всего.
  • Telegram — переадресация в чат или бот.
  • MAX — сообщение приходит от нашего бота.
  • Другой номер — SMS дублируется на указанный номер.
  • E-mail — письмо на указанный адрес.
  • Вебхук — POST на ваш URL. Доступен на платных тарифах.

Каналов можно включить сразу несколько. Фильтров два, и работают они вместе: по тексту сообщения (например, только те, где встречается слово «код») и по отправителю. Сообщение уезжает, только если прошло оба.

Где что выполняется. Telegram, push и дублирование на другой номер отправляет сам телефон. Почта и MAX идут через наш сервер — иначе их технически не отправить. На бесплатном «Старте» переадресация идёт не чаще одного сообщения в 30 секунд: если приходит чаще, сообщения встают в очередь и уезжают следом, а не теряются.

Фильтры: шаблоны и переменные

Фильтра два — по тексту сообщения и по отправителю. Каждый работает в одном из трёх режимов:

  • Все — фильтр выключен, проходит любое сообщение.
  • Белый список — проходит только то, что совпало с шаблоном.
  • Чёрный список — проходит всё, кроме того, что совпало с шаблоном.

Шаблон — это регулярное выражение. Совпадение частичное: достаточно, чтобы выражение нашлось где-то внутри строки, привязывать к началу и концу не нужно. Регистр важен: код и КОД — разные шаблоны. Если сообщение проходит по обоим фильтрам сразу, оно уезжает; если хотя бы один отсёк — нет.

Что чаще всего нужно:

  • (?i)код — слово «код» в любом регистре. (?i) в начале выключает чувствительность к регистру для всего шаблона.
  • код|пароль|секрет — любое из перечисленных слов. Вертикальная черта — «или».
  • \d{4,6} — подряд от четырёх до шести цифр: так ловятся коды подтверждения.
  • Сбербанк|900 — в фильтре по отправителю: сообщения от «Сбербанк» или с номера 900.
Спецсимволы. Точка, скобки, звёздочка и другие знаки в регулярных выражениях имеют особое значение. Чтобы искать сам символ, а не его роль, поставьте перед ним обратную косую черту: \. — точка, \$ — знак рубля или доллара.

06Лимиты тарифа

Актуальные лимиты — на странице тарифов. Коротко:

  • Переадресация входящих — без ограничений на всех тарифах. Квота считается только на отправку.
  • Старт — 1 SIM-карта, 50 отправок в месяц; переадресация не чаще 1 сообщения в 30 секунд.
  • Персона — 1 SIM-карта, 300 отправок в месяц; переадресация без задержки, вебхук как канал.
  • Про — до 5 SIM-карт, 1 500 отправок в месяц.
  • Бизнес — до 15 SIM-карт, 5 000 отправок в месяц.
  • Нужно больше — напишите нам, посчитаем под вашу задачу.

07Частые проблемы

Приложение не отправляет и не принимает SMS

  • Проверьте, что в настройках приложения выданы разрешения на SMS и телефон.
  • Проверьте, что у телефона есть подключение к интернету — без него телефон не связан с облаком.
  • На телефонах Xiaomi, Huawei, Samsung — проверьте, что для TextBee разрешён автозапуск (обычно в разделе «Безопасность» настроек телефона). Без этого приложение может останавливаться после перезагрузки или через некоторое время в фоне.

Не приходит шестизначный код

Код выдаётся в личном кабинете сразу, никуда «приходить» отдельно не должен: если кода нет на экране, обновите страницу личного кабинета.

Сообщение отправлено, но получатель его не увидел

Проверьте статус сообщения в личном кабинете или через API. Доставка зависит от мобильного оператора отправляющего телефона, и TextBee не может гарантировать доставку, если у оператора на его стороне произошёл сбой.

Куда обращаться, если ничего из этого не помогло

В Telegram — самый быстрый способ, или на support@textbee.ru.