> ## Documentation Index
> Fetch the complete documentation index at: https://aitextura.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Planfix

> Planfix подключается как канал: ИИ-сотрудник отвечает клиентам комментариями в задачах, а Planfix сам доставляет ответ в тот мессенджер, из которого пришло обращение. Подключение состоит из API-токена, канала в AI Textura и автоматического сценария в Planfix.

<CardGroup cols={2}>
  <Card title="Каналы — обзор" icon="plug" href="/ru/channels">
    Что такое канал и как он работает в AI Textura
  </Card>

  <Card title="Bitrix24" icon="building" href="/ru/channels/bittrix24">
    Другая система с подключением по вебхуку
  </Card>

  <Card title="amoCRM и Kommo" icon="address-book" href="/ru/channels/amocrm">
    Подключение CRM по OAuth
  </Card>

  <Card title="Уведомления" icon="bell" href="/ru/guides/notifications">
    Триггеры и оповещения сотрудников
  </Card>
</CardGroup>

## Как это работает

Planfix — это не мессенджер. Клиент пишет вам в Telegram, WhatsApp, на почту или в чат на сайте, а Planfix превращает обращение в **задачу** и складывает переписку в её комментарии. Ответ сотрудника, написанный комментарием, Planfix отправляет клиенту обратно в тот же канал.

ИИ-сотрудник встраивается в эту схему как обычный сотрудник Planfix:

<Steps>
  <Step title="Клиент пишет">
    Сообщение попадает в задачу Planfix новым комментарием.
  </Step>

  <Step title="Planfix зовёт AI Textura">
    Автоматический сценарий отправляет комментарий на адрес вебхука вашего канала.
  </Step>

  <Step title="ИИ отвечает">
    AI Textura добавляет в задачу ответный комментарий.
  </Step>

  <Step title="Planfix доставляет ответ">
    Клиент получает ответ там же, где написал — в Telegram, WhatsApp или на почте.
  </Step>
</Steps>

<Tip>
  Отдельно подключать мессенджеры не нужно. Все каналы, уже заведённые в вашем Planfix, автоматически становятся доступны ИИ-сотруднику через один канал Planfix.
</Tip>

***

## Что понадобится

| Что                                          | Где взять                                                                                        |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Аккаунт Planfix** с правами администратора | Ваш Planfix — нужны разделы «Доступ к API» и «Автоматические сценарии»                           |
| **Домен аккаунта**                           | Адрес вашего Planfix целиком, вместе с зоной: `acc.planfix.ru` или `acc.planfix.com`             |
| **API-токен**                                | Создаётся на шаге 1                                                                              |
| **Сотрудник-бот в Planfix**                  | Обычный сотрудник, на которого будут назначаться задачи для ИИ. Можно использовать существующего |

<Note>
  Подключение выполняется в три шага и занимает около 15 минут. Порядок важен: адрес вебхука появляется только **после** сохранения канала, а без него не настроить сценарий.
</Note>

***

## Шаг 1. Создайте API-токен в Planfix

<Steps>
  <Step title="Откройте раздел API">
    В Planfix перейдите в **Управление аккаунтом** → **Доступ к API** → **REST API**.
  </Step>

  <Step title="Создайте новый ключ">
    Нажмите создание нового API-ключа и задайте ему понятное имя — например, «AI Textura».
  </Step>

  <Step title="Выдайте права (scope)">
    Токену нужны как минимум эти права:

    | Право              | Зачем                                                       |
    | ------------------ | ----------------------------------------------------------- |
    | `comment_add`      | Писать ответы комментариями                                 |
    | `contact_readonly` | Узнавать, от какого клиента пришло обращение                |
    | `file_add`         | Прикреплять файлы                                           |
    | `file_readonly`    | Читать вложения клиента                                     |
    | `task_update`      | Переназначать задачу при передаче оператору                 |
    | `user_readonly`    | Получать список сотрудников и групп для поля «Назначить на» |
  </Step>

  <Step title="Скопируйте токен">
    Сохраните его во временное место — он понадобится на следующем шаге.
  </Step>
</Steps>

<Warning>
  API-токен даёт полный доступ к вашему аккаунту Planfix. Не пересылайте его в мессенджерах и не храните в общих документах. В AI Textura после сохранения токен скрывается и больше не показывается.
</Warning>

***

## Шаг 2. Создайте канал в AI Textura

<Steps>
  <Step title="Откройте сотрудника">
    Перейдите в [ИИ-сотрудники](/ru/guides/ai-employees) → выберите сотрудника → вкладка **Канал** → подвкладка **Подключить новый**.
  </Step>

  <Step title="Выберите Planfix">
    Найдите в списке платформ **Planfix** и нажмите **Создать**.
  </Step>

  <Step title="Заполните два обязательных поля">
    * **Домен** — адрес аккаунта целиком, вместе с зоной: `acc.planfix.ru`. Можно вставить и со `https://` — лишнее уберётся само.
    * **API-токен** — ключ из шага 1.
  </Step>

  <Step title="Нажмите «Подключить»">
    Канал сохранится, и AI Textura сгенерирует для него **адрес вебхука** — уникальный и секретный.
  </Step>

  <Step title="Скопируйте адрес вебхука">
    Откройте только что созданный канал во вкладке **Подключённые**. В поле **Вебхук URL** нажмите кнопку копирования. Этот адрес нужен на шаге 3.
  </Step>
</Steps>

<Note>
  Поле **Вебхук URL** пустует, пока канал не сохранён — так и должно быть. Адрес генерируется один раз при создании канала и дальше не меняется.
</Note>

<Warning>
  Адрес вебхука — это пароль. Кто угодно, зная его, сможет присылать вашему ИИ-сотруднику сообщения от имени клиентов. Не публикуйте его.
</Warning>

***

## Шаг 3. Настройте автоматический сценарий в Planfix

Сценарий — это то, что заставляет Planfix звать AI Textura при каждом новом сообщении клиента.

<Steps>
  <Step title="Откройте сценарии">
    В Planfix перейдите в **Управление аккаунтом** → **Автоматические сценарии** и нажмите **Новый сценарий**.
  </Step>

  <Step title="Задайте событие">
    **Событие, при котором будет запущен сценарий** — *Добавлен комментарий и задача соответствует условиям*.
  </Step>

  <Step title="Задайте условия">
    Добавьте два условия и соедините их логикой **1 И 2**:

    1. **Автор комментария — контакт** — чтобы бот отвечал только клиенту, а не на комментарии коллег.
    2. **Исполнитель = ваш сотрудник-бот** — чтобы бот работал только в тех задачах, которые ему поручены.
  </Step>

  <Step title="Добавьте действие «Послать HTTP-запрос»">
    В разделе **Выполнить следующие операции** выберите действие **Послать HTTP-запрос** и заполните:

    * **Метод** — `POST`
    * **URL** — адрес вебхука, скопированный на шаге 2
    * **Тип** — `application/json`
    * **Содержимое запроса** — переключите на вкладку **ПАРАМЕТРАМИ** (не «Текстом»)
    * **Авторизация** — *Без авторизации*
  </Step>

  <Step title="Добавьте параметры">
    Добавьте шесть параметров — имена слева должны совпадать буква в букву:

    | Параметр      | Значение                                             |
    | ------------- | ---------------------------------------------------- |
    | `taskId`      | `{{Задача.Номер}}`                                   |
    | `commentId`   | `{{Комментарий.Идентификатор}}`                      |
    | `text`        | `{{Комментарий.Текст}}`                              |
    | `contactId`   | `{{Задача.Постановщик.Номер}}`                       |
    | `contactName` | `{{Задача.Постановщик.ФИО}}`                         |
    | `fileIds`     | `{{Комментарий.Прикреплённые файлы.Идентификаторы}}` |
  </Step>

  <Step title="Сохраните сценарий">
    В блоке **Уведомление об изменениях** оставьте **Уведомлять** и сохраните.
  </Step>
</Steps>

<Warning>
  Для `contactId` выбирайте именно **«Номер»** постановщика, а не «Идентификатор». «Идентификатор» возвращает другой, технический номер — с ним ответ не дойдёт до клиента в его мессенджер.
</Warning>

<Tip>
  Чтобы каждая новая задача сразу попадала к ИИ, назначьте сотрудника-бота исполнителем **по умолчанию в шаблоне задачи**. Иначе исполнителя придётся ставить руками, и до этого момента сценарий не сработает.
</Tip>

***

## Дополнительные поля: контекст из задачи

Кроме шести обязательных параметров вы можете передать ИИ-сотруднику **любые поля задачи** — город, номер договора, тариф, тему обращения. Он получит их вместе с сообщением и будет учитывать в ответе.

Добавьте в тот же список параметров ещё строки — имя придумываете сами, оно и станет подписью для ИИ:

| Параметр         | Значение                  | Что увидит ИИ                    |
| ---------------- | ------------------------- | -------------------------------- |
| `Тема обращения` | `{{Задача.Название}}`     | Тема обращения: Не приходит счёт |
| `Город`          | `{{Задача.Поле.Город}}`   | Город: Казань                    |
| `Номер договора` | `{{Задача.Поле.Договор}}` | Номер договора: ДГ-7788          |

<Tip>
  Называйте параметры человеческим языком — ИИ читает именно эти подписи. `Номер договора` понятнее, чем `contract_no`.
</Tip>

<Note>
  Ограничения: не больше **15** дополнительных полей, длина названия — до 60 символов, длина значения — до 300 символов. Пустые поля не передаются.
</Note>

***

## Настройки канала

Откройте канал во вкладке **Подключённые**, чтобы изменить его настройки.

| Настройка                        | Что делает                                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Домен**                        | Адрес аккаунта Planfix вместе с зоной                                                                                        |
| **API-токен**                    | Ключ доступа. После сохранения скрывается — заполняйте, только если хотите заменить его на новый                             |
| **Вебхук URL**                   | Адрес для сценария Planfix. Только для чтения                                                                                |
| **Назначить на**                 | Сотрудник или группа, на которых переназначается задача при передаче оператору. Если пусто — бот просто снимет себя с задачи |
| **Посылать ответ как заметку**   | Ответы ИИ становятся скрытыми: их видят только сотрудники Planfix, клиент — нет                                              |
| **Разрешить передачу оператору** | Позволяет ИИ самому передать обращение живому сотруднику. По умолчанию выключено                                             |
| **Когда передавать оператору**   | Ваше описание словами, в каких случаях звать человека                                                                        |

### Режим заметки

Включите **«Посылать ответ как заметку»**, если хотите сначала посмотреть, что отвечает ИИ, и не показывать это клиенту. Ответы будут появляться в задаче скрытыми комментариями — с замочком, видимыми только вашим сотрудникам.

<Tip>
  Удобный способ обкатать нового сотрудника на реальных обращениях без риска. Когда ответы устроят — выключите переключатель, и ИИ начнёт отвечать клиентам напрямую.
</Tip>

***

## Передача оператору

Если включить **«Разрешить передачу оператору»**, ИИ сможет сам позвать живого сотрудника. Происходит это так:

1. ИИ пишет клиенту, что подключает коллегу.
2. В задачу добавляется **скрытая заметка** с кратким пересказом разговора — чтобы сотрудник не перечитывал всю переписку.
3. Задача переназначается на того, кто указан в поле **«Назначить на»**.
4. Бот перестаёт отвечать — сценарий больше не срабатывает, потому что исполнитель уже не он.

### Когда передавать

Поле **«Когда передавать оператору»** заполняется обычными словами, без всякого синтаксиса. Например:

```
Если спрашивают про возврат денег или если сумма заказа больше 100 000 ₽
```

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

<Warning>
  Передача оператору выключена по умолчанию — включайте её осознанно. Если поле **«Назначить на»** не заполнено, задача останется без исполнителя: бот с неё уйдёт, но конкретного сотрудника система не назначит.
</Warning>

***

## Вложения

Если в сценарии передан параметр `fileIds`, ИИ-сотрудник получает файлы, которые клиент приложил к комментарию:

| Тип файла               | Что происходит                                                  |
| ----------------------- | --------------------------------------------------------------- |
| **Голосовое сообщение** | Распознаётся в текст, ИИ отвечает по содержанию                 |
| **Изображение**         | ИИ рассматривает картинку и отвечает по ней                     |
| **Другие файлы**        | ИИ получает имя файла — чтобы ответить осмысленно, а не вслепую |

<Note>
  Обрабатывается до **3 файлов** на один комментарий, размер каждого — до 15 МБ.
</Note>

***

## Проверьте, что всё работает

<Steps>
  <Step title="Создайте задачу">
    В Planfix создайте задачу и назначьте исполнителем сотрудника-бота.
  </Step>

  <Step title="Напишите от лица клиента">
    Добавьте комментарий от контакта — или попросите клиента написать в подключённый канал.
  </Step>

  <Step title="Дождитесь ответа">
    В течение нескольких секунд в задаче появится комментарий от ИИ-сотрудника.
  </Step>

  <Step title="Проверьте доставку">
    Убедитесь, что ответ ушёл клиенту в его мессенджер — если, конечно, не включён режим заметки.
  </Step>
</Steps>

***

## Частые вопросы

<AccordionGroup>
  <Accordion title="Почему поле API-токена пустое, когда я открываю настройки канала?">
    Так и задумано. Токен даёт полный доступ к аккаунту Planfix, поэтому после сохранения мы его больше не показываем — даже вам. Канал при этом работает: токен хранится и используется. Заполняйте поле, только если хотите заменить ключ на новый.
  </Accordion>

  <Accordion title="Список «Назначить на» пустой и просит заполнить домен и токен.">
    Список сотрудников приходит из Planfix, и для запроса нужен токен — а он, как описано выше, в форме не показывается. Вставьте токен в поле ещё раз, список подгрузится, выберите сотрудника и сохраните.
  </Accordion>

  <Accordion title="ИИ не отвечает на комментарии. Что проверить?">
    По порядку: (1) исполнитель задачи — сотрудник-бот, указанный в условиях сценария; (2) комментарий написан **контактом**, а не сотрудником — на коллег сценарий не реагирует намеренно; (3) сценарий включён, а в действии указан правильный адрес вебхука; (4) канал в AI Textura активен и сотрудник в статусе «Active»; (5) рабочее расписание сотрудника позволяет ему отвечать сейчас.
  </Accordion>

  <Accordion title="Planfix пишет «Scope denied» или «Нет доступа».">
    Токену не хватает прав. Вернитесь в **Управление аккаунтом** → **Доступ к API** и выдайте ключу все шесть прав: `comment_add`, `contact_readonly`, `file_add`, `file_readonly`, `task_update`, `user_readonly`.
  </Accordion>

  <Accordion title="Ответ появляется в задаче, но клиенту не приходит.">
    Почти всегда причина в параметре `contactId`: в сценарии выбрано «Идентификатор» вместо «Номер». Замените значение на `{{Задача.Постановщик.Номер}}`. Вторая возможная причина — включён режим «Посылать ответ как заметку»: тогда ответ виден только сотрудникам.
  </Accordion>

  <Accordion title="Не начнёт ли бот отвечать сам себе?">
    Нет. Во-первых, условие сценария «Автор комментария — контакт» отсекает комментарии бота. Во-вторых, Planfix не запускает сценарии для комментариев, добавленных через API. В-третьих, AI Textura отбрасывает повторы по номеру комментария. Три независимые защиты.
  </Accordion>

  <Accordion title="Можно ли подключить несколько аккаунтов Planfix?">
    Да. Каждый аккаунт — отдельный канал со своим доменом, токеном и адресом вебхука. Помните правило: один канал привязывается к одному ИИ-сотруднику.
  </Accordion>

  <Accordion title="Что будет, если менять сценарий или отключить канал?">
    Отключённый канал перестаёт принимать сообщения — Planfix продолжит слать запросы, но ответов не будет. Если нужно временно вернуть переписку живым сотрудникам, лучше выключить ИИ-сотрудника, а не канал: тогда история диалогов сохранится.
  </Accordion>
</AccordionGroup>