Как вывести информацию из сущности CRM в чат

Для вывода информации из сущности CRM в чат можно воспользоваться двумя способами:
  • Метками
  • Переменными

И метки и переменные имеют уникальный код, который вставляется в сообщение и который чат-бот потом меняет на соответствующую ему информацию.


Работа с метками

Метки работают только с сущностями Битрикс24, привязанными к чату и поддерживают только следующие типы сущностей:
  • Лид
  • Компания
  • Контакт

Для одной метки настраивается вывод информации сразу из трёх доступных типов сущностей CRM.
При выводе информации из метки бот руководствуется описанными ниже принципами.
Если из трёх типов к чату привязана только одна сущность - чат-бот выведет в чат информацию из неё.
Если же к чату привязаны две или более сущности, то чат-бот выведет в чат информацию из сущности, приоритет которой выше в следующем порядке: Контакт - Компания - Лид.
То есть данные из сущности Контакт имеют приоритет над данными из сущности Компания, а данные из Компании, соответственно, имеют приоритет над данными из Лида.
Например:
  • если к чату будет привязаны Компания и Контакт, то при выводе метки чат-бот выведет информацию из Контакта,
  • если будут привязаны Лид и Контакт, то информация также будет выведена из Контакта.

При выводе метки берется актуальная на момент вывода информация из сущности CRM. Метки нельзя проверять в условиях и записывать их значения в другие сущности CRM. Также они не поддерживают сложные типы полей, вроде привязки к элементам списка.

Работа с переменными

Переменные предоставляют более широкие возможности по работе с данными из CRM и в них можно хранить информацию почти из всех типов сущностей CRM Битрикс24: 
  • Лид
  • Компания
  • Контакт
  • Сделка
  • Элемент списка
  • Элемент смарт процесса

  • Чтобы вывести какую-либо информацию из CRM в чат с помощью переменных, в первую очередь потребуется записать нужную информацию в переменную. А уже после этого содержимое переменной можно выводить в чат, проверять в условиях, сохранять в другие сущности CRM и выполнять другие операции. Если сущность CRM, из которой было получено значение, будет изменена или удалена - переменная не изменится - она будет хранить записанное в нее ранее значение до тех пор, пока вы ее не перезапишете или она не сбросится по истечению времени.

    Как записать информацию из поля сущности CRM в переменную

    Сохранить информацию из сущности CRM в переменную можно с помощью действия "Заполнение переменной", добавив его в нужное место сценария чат-бота:


    Действие заполнения переменной имеет ряд параметров, которые необходимо заполнить.

    • Переменная. Здесь указывается переменная в которую нужно записать информацию (обратите внимание, что переменная, также как и поле сущности CRM имеет различные типы, поэтому не стоит пытаться записать текст в переменную с типом "число", но можно записать число в переменную с типом "строка").
    • Если переменная не пуста. Здесь необходимо указать поведение действия на случай, если переменная уже заполнена во время выполнения действия - если вы хотите обновить переменную, укажите значение "перезаписать", иначе укажите значение "оставить старое".
    • Тип заполнения - укажите "значение".
    • Заполнить из - укажите "заполнить из CRM".
    • Сущность CRM. Здесь укажите тот тип сущности CRM, из которого вы хотите получить информацию. То есть если вы хотите записать в переменную какое-то значение из поля Сделки, то укажите Сделка.
    • Свойство. Здесь укажите поле выбранной сущности, из которого будете записывать информацию в переменную.
    • Взять сущность из чата/переменной. Самый важный параметр, так как именно он определяет, с какой конкретно сущностью чат-бот будет работать - из какой конкретно сущности будет получаться информация и записываться в переменную. Если вы уверены, что нужная вам сущность привязана к чату, в котором работает чат-бот, то можете указать "из чата", если же сущность не привязана к чату или вы не уверены, что она точно будет в чате на момент выполнения действия, а также если у вас несколько сущностей одного типа (как часто бывает со сделками), то укажите переменную в которую вы сохранили нужную вам сущность. Обратите внимание, что в случае указания переменной, откуда будет браться конкретная сущность CRM, такая переменная должна быть заполнена предварительно до выполнения действия получения информации из полей сущности.

    Как записать нужную сущность CRM в переменную в случае, если сущность берется из переменной, а не из чата.

    Сохранить нужную сущность CRM в переменную можно множеством разных способов и выбирать конкретный способ необходимо вам самостоятельно в зависимости от вашей конкретной ситуации.
    Примеры:
    • Вы можете создать новую сущность прямо в процессе работы сценария чат-бота. Как это сделать вы можете прочитать здесь.
    • Найти нужную сущность в CRM с помощью действия "Поиск в базе CRM" и записать результат поиска в переменную. О том как работать с поиском вы можете прочитать в инструкции.
    • Записать в переменную сущность, привязанную к свойству другой сущности, находящейся в чате или другой переменной, также с помощью действия "Заполнение переменной" (Например, если в чате есть контакт, но нет компании, а при этом она привязана к этому контакту в каком-то его свойстве, то можно записать компанию в переменную из этого контакта).
    • Записать в переменную конкретную сущность CRM, если вдруг по какой-то причине она одинаковая для всех чатов всех клиентов (Маловероятно, но и такое бывает).


    Переменная
    Указывается переменная в которую нужно записать информацию (в данном случае у неё должен быть тип "Связь с сущностью CRM").

    Если переменная не пуста
    Если вы хотите обновить переменную, укажите значение "перезаписать", иначе укажите значение "оставить старое".


    Тип заполнения
    У вас несколько вариантов.

    "Значение" + Заполнить из "указать значение"
    Подойдёт вам в том случае, если вы знаете конкретную сущность и она для всех ваших чатов всех клиентов одинаковая по какой-то причине.



    "Значение" + Заполнить из "заполнить из CRM"
    Подойдёт вам в том случае, если нужная вам сущность сохранена в одном из полей уже известной вам сущности:
    • Сущность CRM - укажите тот тип сущности CRM к которому привязана нужная вам сущность CRM.
    • Свойство - укажите поле выбранного типа сущности CRM в котором хранится нужная вам сущность CRM (например, это может быть поле "Компания" у контакта или любое поле с типом "Привязка к элементам CRM").
    • Взять сущность из чата/переменной - указываете откуда брать сущность CRM к которой привязана нужная вам сущность CRM.


    "Из чата"
    Подойдёт вам в том случае, если нужная вам сущность CRM уже привязана к чату.


    "С максимальным ID"
    Подойдёт вам в том случае, если нужная вам сущность только что создана. Чем новее сущность, тем больше у неё ID. Обратите внимание, что в этом случае будет выбрана сделка из всех сделок CRM с максимальным ID, даже не имеющая отношения к текущему чату. Так что будте аккуратнее при использовании этой возможности.


    "Последняя изменённая"
    Подойдёт вам в том случае, если нужная вам сущность недавно изменена. Как правило изменяются именно актуальные сущности, например, это может быть полезно при наличии дублей контактов или нескольких сделок, одни из которых уже закрыты и не актуальны. Обратите внимание, что в этом случае будет выбрана последняя измененная сущность из всех сущностей CRM указанного типа, даже не имеющая отношения к текущему чату. Так что будте аккуратнее при использовании этой возможности.



    Рассмотрим на примере

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

    Для этого нам нужно вывести имя из контакта. Если контакт привязан к чату, можем сделать это с помощью меток.

    Создадим новую метку с кодом "NAME" и с названием "Имя". Так как мы работаем с контактами, а не лидами, то укажем у контакта нужное нам поле "Имя".



    Далее в нужном нам узле в действии "Отправить текст" укажем код этой метки.



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





    Тоже самое мы можем сделать с помощью переменной.

    Создадим аналогичную переменную, с кодом "NAME" и названием "Имя". Тип данных выбираем "Строка".



    Теперь нужно указать, что именно мы храним в этой переменной. Делаем это с помощью действия "Заполнение переменной":
    • Переменная - указывается нашу переменную "Имя".
    • Если переменная не пуста - перезаписываем.
    • Тип заполнения - указываем "значение".
    • Заполнить из - указываем "заполнить из CRM".
    • Сущность CRM - указываем "контакт".
    • Свойство - укажите поле контакта "Имя".
    • Взять сущность из чата/переменной - в нашем случае сущность привязана к чату, поэтому указываем "Взять сущность из чата".



    Далее в действии "Отправить текст" вставляем код нашей переменной. Обратите внимание, что все переменные имеют префикс "VAR."



    Получаем простой узел.



    Результат получаем аналогичный.



    Преимущество использования переменных в данном случае может быть в возможности использовать условие.

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

    Тогда мы добавить два действия "Отправить текст".

    Первому, в котором мы указываем имя, добавить условие "Имя заполнено".



    Второму аналогичное условие, но с отрицанием.



    И теперь, если при старте диалога имя клиента не известно - чат-бот попросит его представиться, иначе поприветствует по имени.





    Предположим, у нас задача посложнее. Нам также известен клиент, но у него несколько сделок. Каждая сделка - это товар. Клиент хочет узнать информацию о товаре по трек номеру.

    Для начала спросим у него трек номер. Для этого нам подойдёт тип ответа "ждать произвольного ответа пользователя". В действии "Отправить текст" просим клиента указать трек номер товара, затем в строковую переменную "Трек номер" сохраняем полученный ответ и переводим в другой узел.



    В другом узле с помощью действия "Поиск в базе CRM" ищем сделку с товаром по указанному трек номеру. Найденная сделка сохраняется в переменную "Сделка" с типом "Связь с сущностью CRM".



    Далее с помощью действия "Заполнение переменной" сохраняем название товара:
    • Переменная - указывается нашу переменную "Имя".
    • Если переменная не пуста - перезаписываем.
    • Тип заполнения - указываем "значение".
    • Заполнить из - указываем "заполнить из CRM".
    • Сущность CRM - указываем "сделка".
    • Свойство - укажите поле контакта "Название".
    • Взять сущность из чата/переменной - в нашем случае сущность сохранена в переменную, поэтому указываем нашу переменную "Сделка".



    И осталось уточнить у клиента, тот ли товар он искал.



    В итоге получаем следующие узлы.



    И так с помощью переменных мы можем легко выводить данные сразу из нескольких сущностей CRM.