🤖

Боты Ассорти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","topic":"usrYYYY",
#              "seq":1,"text":"/status","ts":"..."}]}

Передавайте offset = последний полученный update_id, чтобы не получать старое повторно. Отвечать — sendMessage с to = from из апдейта.

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

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

Готовый пример: эхо-бот на 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" — так бот понимает, какая кнопка нажата.

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

Бот может прислать картинку или файл по ссылке (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 секунд.

Ограничения

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