# Данные из внешнего события

Source: https://docs.botman.pro/a/166-dannye-iz-vneshnego-sobytiya

Функция «Данные из внешнего события» позволяет боту получить информацию, которую присылает платформа в момент действия пользователя:\
например, когда он написал сообщение, нажал кнопку, подписался или отправил файл.

То есть бот может вставить в ваш сценарий те данные, которые реально пришли от Telegram, ВКонтакте или другой платформы.

💡 Например:\
Пользователь написал сообщение «Привет» в Telegram.\
Платформа присылает событие, где есть текст сообщения.

Вы можете получить его так:\
`{{update("message.text")}}` → Привет

То же самое можно сделать с ID чата, ID пользователя, языком, вложениями и другими полями, которые приходят в webhook.

Используйте эту функцию, если хотите работать со старыми или нестандартными полями, которые ещё не стали системными переменными,\
или если нужно показать пользователю то, что он отправил (например, «Вы написали: …»).

---

## Как вставить функцию

**1️⃣ Откройте нужный шаг**\
Например, Сообщение, если хотите показать пользователю данные, или Действие, если хотите передать их в интеграцию.

**2️⃣ Нажмите кнопку </>** — “Выбор переменных и функций”\
Откроется окно со всеми доступными системными функциями.

**3️⃣ Перейдите во вкладку** “Системные функции”

**4️⃣ Выберите “**Данные из внешнего события”\
После выбора в текст подставится метка функции — чип с названием.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/3e1a2b980ee930348837eb3656cda5566f67b7f391b455ea92fb66da5b42f368.png)

**5️⃣ Откроется окно с настройками**\
Там нужно указать:

- Путь (path) — откуда брать данные из входящего события;
- Резервное значение (по желанию) — если по указанному пути ничего не найдено.

**6️⃣ Сохраните изменения**

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/4832287d9fb3d7f807814e2da3594407ee10c978f975274a9bb4f578ea89a3d8.png)

В окне вы увидите:

- Поле «Путь к значению» — обязательное
- Поле «Резервное значение» — необязательное
- Кнопку сохранения, которая станет активной, когда путь заполнен

---

**Как заполнить настройки**

После вставки функции откроется окно, где нужно указать два параметра:

**1️⃣ Путь к данным (path)**

Это самое главное поле.

Здесь вы пишете откуда бот должен взять данные внутри события (webhook), которое пришло от соцсети.

Примеры популярных путей:

- message.text — текст сообщения
- message.chat.id — ID чата
- message.from.language\_code — язык пользователя

Вы просто указываете путь — и если это поле существует в событии, бот вставит его значение.

**💡 Подсказка**

Путь всегда пишется через точки, без скобок, кавычек, слэшей и пробелов.

❌ Нельзя:

- message\["text"\]
- message/text
- object.message\[from\_id\]
- message. text (с пробелом)

✔ Можно:

- message.text
- object.message.from\_id

Если поле пустое или путь указан с ошибкой — функция просто вернёт fallback (если он указан) или 0.

**2️⃣ Резервное значение (fallback) — по желанию**

Это «план Б» — что показать, если по пути данных не нашлось.

Сюда можно ввести:

- текст (например, “нет данных”),
- число (например, 0),
- переменную.

📌 Это поле не обязательно, но полезно, если путь может отсутствовать (например, пользователь отправил файл вместо текста).

---

**Как работает функция на практике**

Функция подставляет данные только в тот момент, когда сценарий запускается реальным внешним событием —\
например, пользователь написал сообщение, нажал кнопку или прислал вложение.

Ниже разберём, что бот получит в самых распространённых ситуациях.

**📲 Примеры работы в Telegram**

Когда пользователь пишет «Привет», Telegram отправляет боту событие с такой структурой (упрощённо):

{\
"message": {\
"text": "Привет",\
"chat": {\
"id": 123456789\
},\
"from": {\
"language\_code": "ru"\
}\
}\
}

Теперь можно получить любые поля:

**✔ Что вернёт функция**

{{update("message.text")}}\
→ Привет

{{update("message.chat.id")}}\
→ 123456789

{{update("message.from.language\_code")}}\
→ ru

{{update("message.nonexistent", "Нет такого поля")}}\
→ Нет такого поля

💡 **Если путь указан неверно — будет возвращён fallback или 0.**

**📲Примеры работы во ВКонтакте**

В ВК данные приходят в другом формате.\
Например, пользователь отправил сообщение «Привет»:

{\
"object": {\
"message": {\
"text": "Привет",\
"from\_id": 987654321\
}\
}\
}

Теперь можно получить:

{{update("object.message.text")}}\
→ Привет

{{update("object.message.from\_id")}}\
→ 987654321

**Как протестировать вручную**

1. Добавьте шаг Сообщение.
2. Вставьте функцию, например:

   Вы отправили: {{update("message.text")}}
3. Откройте своего бота и отправьте сообщение.
4. Если путь указан правильно — бот вернёт ваш текст.

📌 Если бот вернул пусто — чаще всего путь неверный или данные пришли в другом месте события.

---

**Что важно помнить**

Функция работает только с **реальными событиями**, которые пришли в Botman от соцсети. Если события нет — данных тоже нет.

Если пользователь ранее отправлял сообщение, но сейчас запустил другой триггер — данные старого webhook не доступны.

**Разные платформы — разные пути**

Telegram и VK присылают данные в разных структурах:

- **Telegram** → message.text, message.chat.id
- **VK** → object.message.text, object.message.from\_id

Нужно использовать путь именно той платформы, в которой запускается сценарий.

**Примечания**

- Функция работает **только в контексте реального события**, которое приходит от Telegram, ВКонтакте или другой платформы.\
  Если события нет — функция не подставит данные.
- Данные извлекаются строго по указанному пути.\
  Если путь неправильный, хоть на один символ, — вернётся fallback или 0.
- Разные платформы присылают разную структуру webhook.\
  Поэтому пути тоже отличаются:

  - Telegram → message.text
  - ВКонтакте → object.message.text
- Если поле отсутствует в webhook (например, пользователь отправил стикер, а вы пытаетесь получить message.text) — вернётся fallback или 0.
- Функция безопасна:\
  бот никогда не покажет ошибку пользователю,\
  просто вернёт пусто или резервное значение.
- Функция подходит для получения дополнительных и редких полей,\
  которые бот не обрабатывает автоматически как системные переменные.

---

**Мини-чек-лист перед использованием**

- Перед запуском сценария убедитесь, что:
- Сценарий действительно запускается внешним событием (входящее сообщение, клик по кнопке и т.д.)
- Указан корректный путь (path) — без ошибок, кавычек и лишних символов
- Путь соответствует структуре платформы (Telegram ≠ VK)
- Поле, к которому вы обращаетесь, реально может прийти в webhook
- При необходимости задано резервное значение (fallback)
- Вставка выполнена через </> Системные функции → Данные из внешнего события
- Функция протестирована вручную (отправьте тестовое сообщение своему боту)

**✨ Совет**

Для удобной работы с функцией используйте простое правило:

Сначала отправьте сообщение боту → посмотрите, какие данные реально пришли → и только потом указывайте путь.

Так вы всегда будете уверены, что путь правильный, а функция вернёт нужное значение.

Если вы работаете сразу с несколькими платформами (например, Telegram + ВКонтакте),\
делайте отдельные сценарии или условия — у них разные структуры webhook.

И обязательно ставьте fallback, если поле может отсутствовать — так бот всегда покажет пользователю аккуратный и понятный текст, даже когда данных нет.

---

**Официальные ссылки на документацию webhook**

**📘 Telegram Webhook API**

Telegram подробно описывает структуру объекта Update, который приходит в webhook.

👉 Официальная документация:\
[https://core.telegram.org/bots/api#update](https://core.telegram.org/bots/api#update)

На этой странице перечислены:

- все типы событий,
- структура message, callback\_query, chat\_member, poll,
- возможные вложенные поля,
- примеры.

Это главный источник, где пользователь может посмотреть, какие поля реально бывают в webhook Telegram.

**📘ВКонтакте Callback API (Webhook)**

У ВК это называется Callback API.\
Структура событий зависит от типа: сообщение, подписка, клики, ответы и многое другое.

👉 Официальная документация:\
[https://dev.vk.com/ru/api/callback/getting-started](https://dev.vk.com/ru/api/callback/getting-started)

👉 JSON-схемы VK API:\
[@GitHub GitHub - VKCOM](https://github.com/VKCOM/vk-api-schema)