SMeetBot API
Разделы и содержание

Разделы

На этой странице

SMeet Bot API

Первый бот

За несколько минут вы создадите бота и получите от него первый ответ. Нужны аккаунт SMeet с подтверждённым e-mail и компьютер с Python 3.9+ или Node.js 22.13+.

Перед началом#

  • Ваш аккаунт. Для создания бота нужен подтверждённый адрес e-mail. У одного человека может быть до 5 ботов.
  • Разрешение в пространстве. Бот создаётся в том пространстве, где вы открыли BotFather. В публичном пространстве создание открывает платформа, в организации её администраторы (см. Организации и доступ). Если создание закрыто, BotFather так и скажет.
  • Примеры. Скачайте их для Python или Node.js. Каждый архив распаковывается в папку smeet-bot-examples с ботами, их README и локальным mock-сервером. Все примеры описаны в разделе Рабочие примеры.

Шаг 1. Создайте бота#

  1. Откройте SMeet BotFather из раздела Мои боты в приложении или откройте чат с @smeet_botfather.
  2. Отправьте /newbot или нажмите Создать бота.
  3. Отправьте имя, которое увидят люди, от 1 до 64 символов, например Помощник поддержки.
  4. Отправьте адрес: от 5 до 32 символов, строчные латинские буквы, цифры и _, в начале буква, в конце _bot, например support_helper_bot.

BotFather отвечает: Готово: бот @support_helper_bot создан. Статус: не подключён. Если адрес занят, зарезервирован или не подходит по правилам, BotFather сохранит имя и попросит другой адрес.

Шаг 2. Получите токен#

Нажмите Получить токен под ответом BotFather. Кнопка открывает защищённый экран токена в вашем приложении; в чат BotFather токен не присылает никогда.

Токен выглядит как sbt1_<key id>_<secret> и показывается один раз. Скопируйте его в менеджер паролей или сразу в файл .env бота. SMeet хранит только хэш токена: если вы его потеряете, выпустите новый на том же экране, и старый сразу перестанет работать.

Любой, у кого есть токен, может действовать от имени вашего бота. Не вставляйте токен в URL, чаты, скриншоты и git-репозитории. Как хранить и менять токен, описано в разделе Эксплуатация.

Шаг 3. Проверьте токен#

getMe подтверждает, что токен работает, и показывает, что SMeet знает о боте. Сначала поместите токен в переменную SMEET_BOT_TOKEN; команда read -rs SMEET_BOT_TOKEN && export SMEET_BOT_TOKEN запросит его без вывода на экран и не оставит в истории командной оболочки.

Shell
curl -s https://messenger.scrile.com/bot-api/v1/getMe \
  -H "Authorization: Bearer $SMEET_BOT_TOKEN"
JSON
{
  "ok": true,
  "result": {
    "id": "5001",
    "username": "support_helper_bot",
    "display_name": "Помощник поддержки",
    "is_bot": true,
    "space": {"id": "1", "kind": "public", "name": "SMeet"},
    "status": "active",
    "delivery_mode": "polling",
    "can_send_files": true
  }
}

id здесь означает идентификатор аккаунта бота: сообщения, которые отправляет бот, несут то же значение в from.id. Токен всегда передаётся в заголовке Authorization. Опечатка или отозванный токен дают 401 с кодом INVALID_TOKEN. Все идентификаторы передаются строками; храните их в коде тоже строками.

Шаг 4. Запустите эхо-бота#

Эхо-бот отвечает на /start и /help коротким текстом, а любой другой текст возвращает без изменений. Обе версии читают SMEET_BOT_TOKEN и SMEET_API_URL из окружения или из файла .env в текущей папке; по умолчанию SMEET_API_URL равен https://messenger.scrile.com/bot-api/v1.

Python#

Shell
unzip smeet-bot-examples-python.zip
cd smeet-bot-examples/python
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env              # впишите токен в SMEET_BOT_TOKEN
python echo_bot.py

Node.js#

Нужен Node.js 22.13 или новее, npm install не нужен: примеры используют только то, что входит в Node.js.

Shell
unzip smeet-bot-examples-node.zip
cd smeet-bot-examples/node
cp .env.example .env              # впишите токен в SMEET_BOT_TOKEN
node echo_bot.mjs                 # или: npm run echo

Программа пишет в лог Running as @support_helper_bot, delivery mode polling и ждёт. Вот вся логика ответа в версии на Python; ключ каждого ответа строится из event_id события, поэтому повторно доставленное событие никогда не даёт второго сообщения:

Pythondocs/bots/examples/python/echo_bot.py
def handle(client: smeet.Client, update: dict) -> None:
    # Only new messages matter here. Button presses, edits (an edit is a correction, not a new
    # command), access changes and update types added in later API versions are ignored.
    if update["type"] != "message":
        return
    message = update["message"]
    client.send_message(
        message["chat"]["id"],
        reply_for(message),
        # Same event, same key: a repeated update never produces a second reply.
        idempotency_key=smeet.action_key(update["event_id"], "reply"),
    )
    log.info("Replied to update %s in chat %s", update["update_id"], message["chat"]["id"])

Шаг 5. Нажмите «Начать»#

Откройте бота в SMeet: найдите его по адресу или откройте https://messenger.scrile.com/u/support_helper_bot. Нажмите Начать.

Бот получает два события: chat_access_changed со статусом started и ваше сообщение /start. В течение секунды приходит ответ:

Text
Hello! Send me any text and I will send it back.
/help shows what I can do.

Отправьте любой текст, и он вернётся. Остановите программу через Ctrl+C и запустите снова: она продолжит с того же места, потому что хранит позицию в echo_bot_state.json.

Если ничего не приходит, смотрите раздел Если бот молчит.

Без токена: mock-сервер#

В обоих архивах есть локальный тестовый двойник Bot API, mock-server/smeet_mock.py. Ему нужен только Python; он обслуживает одного бота с токеном sbt1_mock_localtestonly, а управляющий API под /_mock/ играет роль пользователя. Открывайте каждый терминал в папке, куда распакован архив:

Shell
# терминал 1: mock
python3 smeet-bot-examples/mock-server/smeet_mock.py

# терминал 2: бот
cd smeet-bot-examples/python
export SMEET_API_URL=http://127.0.0.1:8081/bot-api/v1
export SMEET_BOT_TOKEN=sbt1_mock_localtestonly
python echo_bot.py

# терминал 3: вы в роли пользователя
curl -s -X POST localhost:8081/_mock/start -d '{}'      # в ответе есть chat_id, здесь 550
curl -s -X POST localhost:8081/_mock/message -d '{"chat_id": "550", "text": "hello"}'
curl -s localhost:8081/_mock/chats/550

Mock не является SMeet: он следует контракту достаточно точно, чтобы запускать все примеры, но не воспроизводит квоты, ограничения частоты и надёжность настоящего сервера. Прежде чем полагаться на бота, проверьте его с настоящим SMeet.

Шаг 6. Запустите бота на сервере#

Бот отвечает, только пока работает его программа, поэтому засыпающего ноутбука мало. Long polling нужен только исходящий HTTPS, так что подойдёт любой сервер, в том числе за NAT. Unit для systemd с эхо-ботом на Python, папка smeet-bot-examples скопирована в /opt/smeet-bot:

INI
[Unit]
Description=SMeet echo bot
After=network-online.target
Wants=network-online.target

[Service]
User=smeetbot
WorkingDirectory=/opt/smeet-bot/python
ExecStart=/opt/smeet-bot/python/.venv/bin/python echo_bot.py
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target
  • Файл .env с токеном остаётся в рабочей папке, и читать его может только пользователь сервиса. Там же пишется файл состояния echo_bot_state.json.
  • Запускайте одну копию на бота. Вторая копия получает CONSUMER_CONFLICT и ждёт; так работает резервная копия, это не ошибка.
  • systemctl stop отправляет SIGTERM, и примеры корректно завершаются с кодом 0. При ошибке настройки (отозванный токен, режим webhook, бот на паузе, боты выключены в организации) они пишут в лог одну строку с причиной и завершаются с кодом 2; с этим unit systemd пробует снова каждые 30 секунд, пока вы не исправите настройку.
  • Эхо-бот служит учебным примером. Если бот пишет в базу данных, CRM или платёжную систему, начинайте с python/production_poller.py: он сохраняет каждое событие до подтверждения (Надёжная обработка).

Что дальше#