🤖

Боты Ассорти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 "Content-Type: application/json" \
  -d '{"to":"usrXXXX","text":"Новый заказ №123"}'

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

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

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

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

Периодически спрашиваем у Эфира новые сообщения:

curl "https://assortiz.ru/messenger-api/botapi/ТОКЕН_БОТА/getUpdates?offset=0"

# {"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 — данные нажатой кнопки (см. «Кнопки»).

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

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

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

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

import requests, time

BASE = "https://assortiz.ru/messenger-api/botapi/ТОКЕН_БОТА"
offset = 0
while True:
    r = requests.get(f"{BASE}/getUpdates", params={"offset": offset}).json()
    for u in r.get("updates", []):
        offset = u["update_id"]
        requests.post(f"{BASE}/sendMessage",
                      json={"to": u["from"], "text": "Вы написали: " + u["text"]})
    time.sleep(2)

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

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

curl -X POST https://assortiz.ru/messenger-api/botapi/ТОКЕН_БОТА/sendMessage \
  -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 "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 "Content-Type: application/json" \
  -d '{"message_id":64,"text":"Обновлённое меню","buttons":[[{"text":"Дальше","data":"next"}]]}'

# удалить сообщение бота (у всех)
curl -X POST https://assortiz.ru/messenger-api/botapi/ТОКЕН_БОТА/deleteMessage \
  -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 "Content-Type: application/json" \
  -d '{"commands":[
    {"command":"start","description":"Запустить бота"},
    {"command":"status","description":"Статус заказов"}
  ]}'

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

Ограничения

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