Сущности

Если намерения отвечают на вопрос «Что хочет пользователь?», то сущности отвечают на вопрос «С какими данными?». Сущности — это мощный инструмент, который превращает неструктурированный текст пользователя в структурированные данные, готовые к использованию в логике вашего бота.

Представьте, что пользователь пишет: «Хочу заказать пиццу Пепперони на улицу Ленина, 5, квартира 12».

• Намерение: заказ_пиццы

• Сущности: название_пиццы: "Пепперони", адрес: "улица Ленина, 5, квартира 12"

Без сущностей боту пришлось бы задавать кучу уточняющих вопросов. С ними — он сразу получает все нужные данные.

Типы сущностей

Платформа предлагает два вида сущностей: системные (готовые к использованию) и пользовательские (которые вы настраиваете сами).

Системные сущности

Это встроенные распознаватели для самых распространенных типов данных. Вам не нужно их настраивать — просто используйте.

Список системных сущностей

• phone number: Распознает номера телефонов в различных форматах.

• email: Находит адреса электронной почты.

• digits: Извлекает любые числовые значения.

• city: Распознает названия городов.

• sentiment: Определяет эмоциональную окраску сообщения (позитивная, негативная, нейтральная).

• obscene language: Обнаруживает нецензурную лексику.

Пользовательские сущности

Это сущности, которые вы создаете и настраиваете под уникальные задачи вашего проекта. Это самый гибкий инструмент для извлечения специфической информации.

Тип 1: Ключевые слова (Keywords)

Используется, когда вам нужно найти в тексте конкретные термины или их синонимы. Вы создаете словарь, где каждому значению (ключу) соответствует список фраз.

• Пример: Вы продаете одежду. Можно создать сущность product_type.

  • Ключ: футболка → Синонимы: майка, футболочка, t-shirt

  • Ключ: джинсы → Синонимы: джинса, штаны, denim

Теперь, если пользователь напишет "хочу купить синюю майку", бот поймет, что product_type = футболка.

Тип 2: Регулярные выражения (JavaScript RegExp)

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

• Пример: Ваши номера заказов имеют формат ЗАКАЗ-XXXXX, где X — это цифра. Регулярное выражение для их поиска будет выглядеть так:

  ЗАКАЗ-\d{5}

При создании RegExp-сущности в платформе вам не нужно оборачивать выражение в / или указывать флаги (g, i), так как глобальный поиск (g) применяется по умолчанию. Другие флаги применять нельзя.

Тип 3: HTTP-запрос (HTTP request)

Это самый мощный тип сущностей. Он позволяет создать динамический словарь, который загружается из внешнего источника по API. Это полезно, когда список возможных значений часто меняется.

• Пример: У вас есть каталог товаров, который постоянно обновляется. Вы можете настроить HTTP-сущность, которая будет раз в сутки обращаться к вашему API (https://api.yourshop.com/products) и получать актуальный список названий всех товаров. Бот сможет распознавать их в сообщениях без необходимости вручную обновлять список ключевых слов.

Как использовать сущности?

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

1. Как триггер: Сценарий может запускаться, как только в сообщении пользователя будет найдена определенная сущность. Например, если бот обнаружил email, он может запустить сценарий подписки на рассылку.

2. Для получения данных: Внутри сценария (в текстовых реакциях или сниппетах) вы можете получить доступ к значению распознанной сущности и использовать его для персонализации ответов или для передачи в ваши системы.

Именование сущностей Чтобы легко обращаться к сущностям в коде, давайте им имена на латинице в snake_case (например, order_number) или camelCase (например, orderNumber), как обычным переменным.