🤖

Боты АссортиZ — Эфир

Как создать и подключить бота

Бот — это обычный аккаунт Эфира, которым управляет программа. Люди находят его в поиске и пишут как коллеге, а бот отвечает автоматически: присылает уведомления о заказах, отвечает на команды, связывает Эфир с вашими системами. Свой простой API — не Telegram, но по духу похоже.

Шаг 1. Получить бота

Проще всего — прямо в приложении: Профиль → «🤖 Мои боты» → Создать. Вы получите токен бота, и управляете только своими ботами (у каждого свои, изолированно). Дальше используйте токен по API, как описано ниже.

Для API-примеров ниже подставляйте токен вашего бота из «Мои боты». (Вариант для администратора: массовая веб-панель /bots/admin/ под админ-токеном — управляет всеми ботами сразу.)

curl -X POST https://assortiz.ru/messenger-api/botapi/admin/create \
  -H "X-Admin-Token: ВАШ_АДМИН_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"name":"Мой Бот","webhook_url":"https://ваш-сервер/hook"}'

# ответ:
# {"ok":true,"token":"ТОКЕН_БОТА","uname":"bot_xxxx","name":"Мой Бот"}
1name — имя, под которым бот виден людям в поиске.
2webhook_url — необязательно. Если указать, входящие сообщения будут приходить POST-ом на этот адрес (см. шаг 3б).
3Сохраните token из ответа — это секрет бота, с ним он шлёт и принимает сообщения. Показывается один раз.
Бот появится в поиске людей примерно через 15 секунд — шлюз создаёт его аккаунт при первом подключении.

Шаг 2. Бот отправляет сообщение

Самый частый сценарий — уведомления (новый заказ, статус, напоминание):

curl -X POST https://assortiz.ru/messenger-api/botapi/sendMessage \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"to":"usrXXXX","text":"Новый заказ №123"}'

to — кому: usrXXXX (личный чат с человеком) или grpXXXX (группа). Узнать usrXXXX человека можно из входящего сообщения (поле from, шаг 3) или попросив человека первым написать боту.

Шаг 3. Бот принимает сообщения

Два способа на выбор.

а) Long-poll без своего сервера

Спрашиваем у Эфира новые сообщения. Параметр timeout (секунды, до 25) — сколько ждать ответа, если сообщений пока нет: соединение просто держится открытым и закрывается сразу, как только сообщение появится.

curl -H "X-Bot-Token: ТОКЕН_БОТА" \
  "https://assortiz.ru/messenger-api/botapi/getUpdates?offset=0&timeout=25"

# {"updates":[{"update_id":1,"from":"usrYYYY","from_name":"Иван Петров",
#              "topic":"usrYYYY","seq":1,"text":"/status","cb":null,"ts":"..."}]}

Передавайте offset = последний полученный update_id, чтобы не получать старое повторно. Отвечать — sendMessage с to = from из апдейта. from_name — отображаемое имя написавшего; cb — данные нажатой кнопки (см. «Кнопки»).

Всегда указывайте timeout. Без него бот, опрашивающий сервер в цикле, шлёт запросы вхолостую: один такой давал 15 тысяч запросов в сутки — 82 % всего трафика сервера — и ни одного сообщения. С timeout=25 сообщения приходят так же быстро, а запросов в 8 раз меньше.

б) Webhook нужен свой сервер

Укажите webhook_url при создании бота — и Эфир будет слать POST с JSON {"bot_id","from","topic","seq","text","cb"} на каждое входящее сообщение.

Готовый пример: эхо-бот на Python

Отвечает на любое сообщение тем же текстом. Скопируйте, подставьте токен, запустите:

import requests

BASE = "https://assortiz.ru/messenger-api/botapi"
HEAD = {"X-Bot-Token": "ТОКЕН_БОТА"}
offset = 0
while True:
    # timeout=25 — ждём на стороне сервера, а не крутим пустой цикл.
    # Ответ придёт сразу, как только боту напишут.
    r = requests.get(f"{BASE}/getUpdates", headers=HEAD,
                     params={"offset": offset, "timeout": 25}, timeout=40).json()
    for u in r.get("updates", []):
        offset = u["update_id"]
        requests.post(f"{BASE}/sendMessage", headers=HEAD,
                      json={"to": u["from"], "text": "Вы написали: " + u["text"]})

Кнопки под сообщением

Добавьте buttons — ряды кнопок. Callback (нажатие приходит боту в getUpdates полем cb) и URL (открывает ссылку):

curl -X POST https://assortiz.ru/messenger-api/botapi/sendMessage \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "usrXXXX",
    "text": "Подтвердить заказ №123?",
    "buttons": [
      [ {"text":"✅ Да","data":"ok:123"}, {"text":"❌ Нет","data":"no:123"} ],
      [ {"text":"Открыть заказ","url":"https://crm.example/order/123"} ]
    ]
  }'

Когда человек нажмёт «✅ Да», бот получит апдейт с "cb":"ok:123" — так бот понимает, какая кнопка нажата. Нажатие не оставляет следа в переписке (как в Telegram): в ленту ничего не пишется, приходит только cb-апдейт. Обновляйте то же меню через editMessage — чат остаётся чистым.

Ответ на нажатие кнопки тост

Чтобы подтвердить нажатие без нового сообщения в ленте — покажите короткий тост тому, кто нажал (аналог answerCallbackQuery). to = from из апдейта:

curl -X POST https://assortiz.ru/messenger-api/botapi/answerCallback \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"to":"usrYYYY","text":"✓ Заявка принята"}'

Пользователь увидит всплывающий тост, лента не засоряется.

Редактирование и удаление сообщений

Каждый sendMessage возвращает message_id — по нему можно обновлять или удалять сообщение бота. Удобно для «живого» меню: обновляете одно сообщение вместо цепочки экранов.

# при отправке запоминаем message_id
POST .../sendMessage  →  {"ok":true,"message_id":64}

# отредактировать текст и/или кнопки того же сообщения
curl -X POST https://assortiz.ru/messenger-api/botapi/editMessage \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"message_id":64,"text":"Обновлённое меню","buttons":[[{"text":"Дальше","data":"next"}]]}'

# ПОГАСИТЬ кнопки после нажатия (buttons:[] убирает клавиатуру) —
# «Подтвердить заказ?» → после клика «✓ Заказ принят» без живых кнопок
curl -X POST https://assortiz.ru/messenger-api/botapi/editMessage \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"message_id":64,"text":"✓ Заказ принят","buttons":[]}'

# СТАТУС-СООБЩЕНИЕ: редактируем одно и то же сообщение по мере прогресса
# «Деплой идёт…» → editMessage → «✅ Готово за 42с»

# удалить сообщение бота (у всех)
curl -X POST https://assortiz.ru/messenger-api/botapi/deleteMessage \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"message_id":64}'

Важно: отправка асинхронна (~1 сек). Если вызвать edit/delete сразу после send, вернётся 409 not_yet_sent — повторите через секунду.

Картинки и файлы

Бот может прислать картинку или файл по ссылке (text — необязательная подпись):

# картинка
-d '{"to":"usrXXXX","text":"Ваш QR-код","image":{"url":"https://.../qr.png"}}'

# файл
-d '{"to":"usrXXXX","file":{"url":"https://.../otchet.pdf","name":"Отчёт.pdf","size":204800}}'

Меню команд (подсказки «/»)

Объявите команды — и при вводе «/» в чате с ботом человек увидит их списком:

curl -X POST https://assortiz.ru/messenger-api/botapi/setCommands \
  -H "X-Bot-Token: ТОКЕН_БОТА" \
  -H "Content-Type: application/json" \
  -d '{"commands":[
    {"command":"start","description":"Запустить бота"},
    {"command":"status","description":"Статус заказов"}
  ]}'

Команды также удобно задавать в веб-панели. Подсказки появятся в приложении в течение ~15 секунд.

Входящие вебхуки без кода бота

Самый простой способ постить в чат из внешней системы (CI, мониторинг, 1С) — входящий вебхук: один URL, привязанный к конкретной группе. Не нужно писать бота и знать ID чата.

1В приложении: настройки группы → «Интеграции (вебхуки)» → «Создать вебхук». Нужен ваш бот в этой группе (он публикует сообщения от своего имени).
2Скопируйте выданный URL (кнопки «URL» и «curl») и шлите на него POST:
# текст появится в группе от имени вашего бота (доставка ~1-3 сек)
curl -X POST https://assortiz.ru/messenger-api/hook/ХЭШ_ВЕБХУКА \
  -H "Content-Type: application/json" \
  -d '{"text":"✅ Деплой прошёл успешно за 42с"}'

Ключ доступа — сам неугадываемый ХЭШ_ВЕБХУКА в URL (плюс опциональный секрет). Отдельная авторизация не нужна — удобно для скриптов. Удалить вебхук — там же в «Интеграциях».

Токен бота: как передавать

Токен — это пароль бота: с ним можно читать входящие и писать от его имени. Передавайте его заголовком X-Bot-Token, как во всех примерах выше:

-H "X-Bot-Token: ТОКЕН_БОТА"

Старый способ — токен прямо в адресе (/botapi/ТОКЕН/sendMessage) — по-прежнему работает, менять существующих ботов не обязательно. Но для новых лучше заголовок: адрес запроса попадает в журналы (свои, промежуточных прокси, браузера), а заголовки — нет. У нас в журнале ошибок так и лежал полный токен, пока это не исправили.

Токен утёк — выключите бота в «Мои боты» и создайте нового: у бота один токен, сменить его отдельно нельзя.

Ограничения

На главную  ·  Брендбук  ·  Приложение  ·  Открыть Эфир →