Сущности

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

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

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

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

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

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

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

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

phone number

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

email

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

digits

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

city

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

sentiment

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

obscene language

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

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

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

Ключевые слова

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

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

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

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

Регулярные выражения

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

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

ЗАКАЗ-\d{5}

осторожно

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

HTTP-запрос

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

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

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

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

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

warning

Именование сущностей

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