# Make Agent Fast documentation (ru)

---

# Документация

Source: /ru/docs.md

Make Agent Fast даёт вам единое место, чтобы создать клиентского агента, подключить его знания и встречать клиентов на сайте, который у вас уже есть, и в каналах, которыми они уже пользуются.

Клиентский агент для вашей компании — на вашей странице и в ваших каналах сообщений — отвечает только на то, что вы утвердили, а остальное передаёт человеку.

## Начните здесь [#начните-здесь]

Выберите путь в зависимости от того, что хотите запустить первым.

<CardGrid>
  <DocCard href="/ru/docs/getting-started/quickstart" title="Создайте первого агента" description="Вставьте URL сайта, проверьте черновик и включите встраивание." art="quickstart" />

  <DocCard href="/ru/docs/embed/overview" title="Добавьте агента на сайт" description="Установите плавающий загрузчик тегом скрипта или гайдом для фреймворка / CMS." art="embed" />

  <DocCard href="/ru/docs/connectors/overview" title="Подключите канал" description="Отвечайте из WhatsApp, Messenger, Discord и других поддерживаемых каналов." art="channel" />

  <DocCard href="/ru/docs/api/overview" title="Создавайте через API" description="Автоматизируйте процессы агентов, сайтов, контента, диалогов и операций." art="api" />
</CardGrid>

## Базовый процесс [#базовый-процесс]

<Steps>
  <Step title="Создайте">
    Вставьте URL вашего сайта. Мы просканируем его и подготовим черновик агента. Ничего не запускается без вашего утверждения.
  </Step>

  <Step title="Проверьте">
    Поговорите с агентом, прогоните самопроверку, затем выберите 

    **Утвердить и опубликовать**

    .
  </Step>

  <Step title="Охватите">
    Добавьте встраивание на ваш существующий сайт или подключите канал сообщений.
  </Step>

  <Step title="Улучшайте">
    Добавляйте знания, настраивайте внешний вид и просматривайте диалоги и заявки.
  </Step>
</Steps>

<Callout title="Используйте эти документы с ИИ-ассистентом">
  Каждая страница доступна как Markdown. Откройте меню действий страницы, чтобы скопировать или скачать её, или отправьте её канонический Markdown URL в ChatGPT или Claude. Полный машиночитаемый корпус доступен на [/docs/llms-full.txt](/docs/llms-full.txt).
</Callout>

## Что можно создать [#что-можно-создать]

<FeatureGrid>
  <FeatureItem icon="embed" title="Встраивание на сайт" description="Ассистент поддержки или продаж на сайте, который у вас уже есть, — один тег скрипта." />

  <FeatureItem icon="message" title="Агент в мессенджерах" description="Один агент отвечает клиентам в Telegram, WhatsApp, Messenger, Instagram, Discord или KakaoTalk." />

  <FeatureItem icon="voice" title="Голосовые сценарии" description="Голосовые сообщения, клонирование и живые звонки на поддерживаемых тарифах." />

  <FeatureItem icon="code" title="Автоматизации API" description="Программное управление сайтами, знаниями, диалогами и вебхуками." />

  <FeatureItem icon="chart" title="Инструменты операций" description="Входящие, аналитика, заявки, рассылки, монетизация и контроль использования." />

  <FeatureItem icon="site" title="Оставшиеся размещённые демо" description="Уже опубликованные страницы арендаторов (включая публичные демо) по-прежнему открываются на поддоменах. Новые агенты не получают размещённую маркетинговую страницу." />
</FeatureGrid>

## Получите помощь [#получите-помощь]

Если гайд не ответил на ваш вопрос, используйте элемент обратной связи внизу страницы или обратитесь в поддержку из панели управления. О лимитах продукта и оплате читайте в [Тарифах и ценах](/ru/docs/account/pricing).

---

# Журнал изменений

Source: /ru/docs/account/changelog.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Платформа&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;API&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;Документы&#x22;, icon: &#x22;book&#x22; }]" />

## 2026-08-27 [#2026-08-27]

* Задокументирован запуск URL-в-агента: ожидание генерации, Проверка и публикация, Утвердить и опубликовать, и активация на первом чате посетителя или заявке.
* Задокументированы внешний вид **Как на сайте** против Светлой/Тёмной и то, что сохранение внешнего вида обновляет живое встраивание (и оставшиеся размещённые страницы) без повторной публикации.
* Выровнены сниппеты встраивания с живыми атрибутами `embed.js` и `?v=` бустером кэша панели.
* Задокументирован живой разговор на тестировщике платформы против опубликованного сайта и встраивания.
* Удалены собственные домены / покупка домена / настройки поддомена как продукт. Встройте агента на существующий сайт клиента. Оставшиеся события дополнения доменов Polar остаются игнорируемыми или отменяемыми.

## 2026-07-28 [#2026-07-28]

* Упрощена история использования: показывает финальные потреблённые кредиты вместо отдельных строк резерва и возврата; крошечное использование теперь отображается как `<0.001`.
* Углы выделения меню действий документации адаптируются к многострочному содержимому, сохраняя совпадающую геометрию триггера и оболочки меню.
* Расширены английские, корейские и узбекские гайды по оплате живых звонков, вводу медиа визуального конструктора, изменениям размещённых поддоменов, контролям приватности/безопасности аккаунта и ленте событий Уведомлений.

## 2026-07-15 [#2026-07-15]

* Представлена двуязычная документационная платформа Make Agent Fast.
* Добавлены постраничный Markdown, скачивания, поиск, действия ChatGPT и Claude.
* Добавлены `/docs/llms.txt`, `/docs/llms-full.txt` и канонические маршруты `.md`.
* Задокументированы публичный API, контракт SDK, вебхуки, встраивания, коннекторы, операции, цены, безопасность и приватность.
* Добавлены гайды по реализации для основных фреймворков и конструкторов сайтов.

## Политика версионирования [#политика-версионирования]

Исправления документации и добавочные поля API могут выходить непрерывно. Ломающие изменения публичного API требуют нового мажорного пути или задокументированного периода миграции.

---

# Тарифы и цены

Source: /ru/docs/account/pricing.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Launch&#x22;, icon: &#x22;layers&#x22; },
{ label: &#x22;Operate&#x22;, icon: &#x22;spark&#x22; },
{ label: &#x22;Scale&#x22;, icon: &#x22;bolt&#x22; },
{ label: &#x22;Пакеты кредитов&#x22;, icon: &#x22;layers&#x22; }
]"
/>

## Сравнение тарифов [#сравнение-тарифов]

| Тариф   | Месячная оплата | Годовой итог | Кредиты в месяц |                          Агенты | Живой голос |                     Клоны голоса | Значок брендинга |
| ------- | --------------: | -----------: | --------------: | ------------------------------: | ----------: | -------------------------------: | ---------------- |
| Launch  |         $15/мес |     $144/год |            1000 |                               1 |  Не включён |                       Не включён | Обязателен       |
| Operate |         $35/мес |     $336/год |            3000 |                               3 |  30 мин/мес |                                1 | Снимаемый        |
| Scale   |         $79/мес |     $758/год |            8000 | Безлимит, честное использование |  90 мин/мес | Несколько, честное использование | Снимаемый        |

Годовая оплата на 20% ниже оплаты месячной цены двенадцать раз. Launch и Operate начинаются с семидневного бесплатного пробного периода без кредитной карты; добавьте карту после дня 7, чтобы агент оставался активным. Scale начинает оплату немедленно и не имеет пробного периода. Когда карта нужна, оплата показывает точную цену, период продления, налог и условия перед покупкой.

Launch — это работающий встроенный агент на этой неделе. Operate — шаг вверх, когда клиенты реально говорят — живой голос, более полный виджет и каналы сообщений. Scale — полная студия: каждый элемент внешнего вида, роли команды и ваши собственные ключи провайдеров.

## Лестница функций [#лестница-функций]

| Возможность         | Launch                            | Operate                                           | Scale                                               |
| ------------------- | --------------------------------- | ------------------------------------------------- | --------------------------------------------------- |
| Агенты              | 1                                 | 3                                                 | Безлимит, честное использование                     |
| Студия виджета      | Акцент, позиция, светлая/тёмная   | + метка загрузчика, пресеты, дополнительные цвета | Каждый элемент (радиус, тень, рамка, шрифт, стекло) |
| Языки агента        | 1                                 | 2                                                 | 4                                                   |
| Приём знаний        | Вставка, URL, файлы               | + YouTube, подкаст, RSS                           | Как в Operate                                       |
| Каналы сообщений    | Существующие подключения работают | Новые подключения                                 | Новые подключения                                   |
| Свои ключи          | Существующие ключи работают       | Существующие ключи работают                       | Сохранение новых ключей                             |
| Приглашения команды | Существующие участники остаются   | Существующие участники остаются                   | Новые приглашения с ролями                          |

Мы не продаём и не привязываем домены клиентов. Встройте агента на сайт, который у вас уже есть.

## Включено в каждый тариф [#включено-в-каждый-тариф]

Все текущие тарифы включают:

* Встраивание на сайт, который у вас уже есть (`embed.js` + `data-agent`).
* Текстовый чат, голосовые сообщения, стандартные голоса, поиск знаний, структурированные FAQ/товары и сбор заявок.
* Встраивание на сайт с точными контролями origin.
* Доступ к публичному API с ключами с областями, OAuth для проверенных приложений, OpenAPI и лимиты частоты по тарифу.
* Аналитику, диалоги, отслеживание использования и возможность покупать пакеты кредитов.

Лимит публичного API Launch — 120 запросов на ключ API в минуту, Operate — 600, Scale — 1 800. Эти лимиты запросов не заменяют права на ресурсы, проверки кредитов, идемпотентность или специфичные для провайдера лимиты. См. [Лимиты частоты](/ru/docs/api/rate-limits).

## Поймите кредиты [#поймите-кредиты]

Кредиты оплачивают учитываемую работу ИИ вроде генерации, ходов агента, эмбеддингов знаний, транскрибации, синтеза речи и клонирования. Это не фиксированное число сообщений: провайдер, модель, длина ввода/вывода, длительность медиа и тип операции меняют стоимость.

Ежемесячные кредиты тарифа пополняются каждый расчётный период. Неиспользованный ежемесячный лимит переносится на один дополнительный цикл, затем истекает. Купленные кредиты пополнения не истекают при активной подписке. Положительный баланс кредитов не разблокирует функцию только для тарифа вроде живых звонков, дополнительных сайтов, клонирования или удаления значка.

Ключи «принеси свой провайдер» могут создавать отдельные списания от OpenAI, Anthropic, Google, Deepgram или ElevenLabs. Сохранение нового ключа только для Scale; уже хранимые ключи продолжают работать. BYOK не конвертирует счета провайдеров в кредиты Make Agent Fast и не устраняет проверки прав платформы. См. [Ключи AI-провайдеров](/ru/docs/account/provider-keys).

## Права на голос [#права-на-голос]

Голосовые сообщения включены во все тарифы, но их транскрибация, модель и работа речи могут расходовать кредиты. Живой голос реального времени использует отдельный ежемесячный лимит минут: ноль на Launch, 30 минут на Operate и 90 минут на Scale.

Клонирование голоса только для Operate/Scale. Operate включает один клон рабочего пространства; Scale поддерживает несколько при честном использовании. Повторное клонирование сайта, уже владеющего клоном, заменяет его вместо расходования нового слота. Клонирование также требует явного согласия, доступности провайдера и достаточных кредитов для операции.

## Агенты и брендинг [#агенты-и-брендинг]

Launch поддерживает одного клиентского агента, Operate — до трёх. Описание безлимитных агентов Scale подчинено честному использованию, а не приглашению создавать злоупотребляющий или автоматизированный объём арендаторов. Агент включает свои знания, конфигурацию встраивания, коннекторы, аналитику и данные диалогов. Оставшиеся размещённые демо-страницы по-прежнему открываются на поддоменах; новые агенты не получают размещённую маркетинговую страницу.

Реферальный значок «Made with Make Agent Fast» остаётся на Launch. Владельцы Operate и Scale могут убрать его с имеющих право опубликованных сайтов.

## Пакеты кредитов [#пакеты-кредитов]

| Покупка       |       Цена | Что меняет                                            |
| ------------- | ---------: | ----------------------------------------------------- |
| Малый пакет   |  $8 разово | Добавляет 1000 кредитов, не истекающих при подписке   |
| Средний пакет | $35 разово | Добавляет 5000 кредитов, не истекающих при подписке   |
| Большой пакет | $90 разово | Добавляет 15 000 кредитов, не истекающих при подписке |

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

## Пробные периоды, продление и отмена [#пробные-периоды-продление-и-отмена]

Бесплатный пробный период Launch/Operate не конвертируется автоматически: на день 7 агент приостанавливается, пока вы не добавите карту. После того как карта в файле, отмена или неудачное продление может убрать активный доступ после применимого перехода периода/статуса провайдера. Встраивания, коннекторы, клиенты API и голосовые звонки могут остановиться, хотя хранимые данные рабочего пространства остаются.

## Выберите тариф [#выберите-тариф]

* Выберите **Launch** для одного встроенного агента с текстом, голосовыми сообщениями и базовым виджетом.
* Выберите **Operate**, когда клиенты начинают говорить: живые звонки, каналы сообщений, пользовательский виджет, два языка или удаление значка.
* Выберите **Scale**, когда несколько агентов в продакшене: каждый элемент виджета, четыре языка, роли команды и ваши собственные ключи API.

Оценивайте по реальным приёмочным тестам, а не только по числу сообщений. Опубликуйте одного репрезентативного агента, измерьте использование текста/голоса/знаний, затем спроецируйте трафик и добавьте запас на повторы, коннекторы, автоматизацию и пики запуска.

## Источник истины по оплате [#источник-истины-по-оплате]

Живая оплата и панель оплаты — источник истины для конкретной покупки. Налоги, представление валюты, способы оплаты, право на пробный период и формулировки провайдера могут меняться по локации и состоянию аккаунта. Если оплата отличается от этой страницы, остановитесь и используйте условия оплаты или обратитесь в поддержку перед оплатой.

---

# Приватность и данные

Source: /ru/docs/account/privacy.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Данные посетителей&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Хранение&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Контроли&#x22;, icon: &#x22;shield&#x22; }]" />

Владелец сайта решает, какие знания, вводы посетителей и интеграции используются для его опыта. Make Agent Fast обрабатывает данные платформы для предоставления сервиса согласно применимым условиям и уведомлению о приватности.

## Уведомление посетителей [#уведомление-посетителей]

Объясняйте использование ИИ, запись, сбор заявок, аналитику и продолжение языком, подходящим опыту и местным требованиям. Не просите агента собирать данные, которые вам не нужны.

## Жизненный цикл данных [#жизненный-цикл-данных]

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

## Контроли владельца [#контроли-владельца]

Страница **Аналитика** сайта может экспортировать собранные заявки как JSON и удалять отдельную заявку. Отчёты аналитики также могут экспортироваться как Markdown, Excel или вид печати/PDF. Экспорт создаёт новую копию под вашим контролем; удаление записи платформы не стирает более раннюю загрузку, связанный диалог, запись внешнего провайдера или данные, удерживаемые по законному требованию.

Используйте **Настройки аккаунта**, чтобы выйти со всех устройств или навсегда удалить аккаунт. Удаление аккаунта сначала пытается остановить подписку платформы, оставшиеся подписки дополнения доменов Polar и ресурсы коннекторов, затем удаляет сайты, агентов, знания, диалоги, заявки, учётные данные API/OAuth, сессии и локально хранимую историю оплаты аккаунта. Если внешняя оплата не может быть подтверждена остановленной, удаление отказывает и оставляет аккаунт нетронутым для безопасного повтора или проверки поддержкой.

## Запросы [#запросы]

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

---

# Ключи AI-провайдеров

Source: /ru/docs/account/provider-keys.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;spark&#x22;, title: &#x22;Генерация текста&#x22;, description: &#x22;Ключи Anthropic, OpenAI и Gemini могут финансировать поддерживаемую генерацию агента.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Речь&#x22;, description: &#x22;Ключи Deepgram и ElevenLabs могут финансировать настроенный конвейер речи.&#x22; },
{ icon: &#x22;shield&#x22;, title: &#x22;Зашифрованное хранение&#x22;, description: &#x22;Полные ключи зашифрованы и никогда не возвращаются после сохранения.&#x22; }
]"
/>

«Принеси свой ключ» (BYOK) позволяет поддерживаемым запросам ИИ использовать ваш аккаунт у AI-провайдера. Сохранение **нового** ключа требует Scale. Уже хранимые ключи продолжают работать на Launch и Operate. Вы по-прежнему платите тариф Make Agent Fast плюс фиксированную комиссию платформы за действие; провайдер выставляет использование модели напрямую вам.

## Поддерживаемые провайдеры [#поддерживаемые-провайдеры]

| Провайдер     | Используется для                                              | Создать или проверить ключ                                                                          |
| ------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Anthropic     | Генерация текста агента                                       | [Документация Anthropic API](https://docs.anthropic.com/en/api/getting-started)                     |
| OpenAI        | Генерация текста агента и настроенные режимы речи             | [Быстрый старт OpenAI API](https://platform.openai.com/docs/quickstart/make-your-first-api-request) |
| Google Gemini | Генерация текста агента и настроенный режим реального времени | [Ключи Gemini API](https://ai.google.dev/gemini-api/docs/api-key)                                   |
| Deepgram      | Речь-в-текст, когда Deepgram — настроенный провайдер STT      | [Ключи Deepgram API](https://developers.deepgram.com/docs/create-additional-api-keys)               |
| ElevenLabs    | Синтез речи и клонирование голоса, когда настроен ElevenLabs  | [Аутентификация ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)                |

Доступность провайдера также зависит от настроенных провайдеров текста, речи, реального времени и клонирования платформы. Сохранение валидного ключа не заставляет каждую функцию использовать этого провайдера.

<Callout title="BYOK отличается от ключа Make Agent Fast API">
  Ключ провайдера авторизует списания и вызовы модели у внешнего AI-провайдера. Ключ `maf_live_...` авторизует ваше ПО вызывать публичный API Make Agent Fast. Никогда не вставляйте один в поле другого.
</Callout>

## Добавьте ключ провайдера [#добавьте-ключ-провайдера]

1. Создайте ограниченный ключ в консоли провайдера и включите оплату или квоту провайдера, если требуется.
2. Откройте **Панель → Настройки → Ключи AI-провайдеров**.
3. Выберите подходящего провайдера и добавьте метку, идентифицирующую его проект или окружение.
4. Вставьте ключ и сохраните его.
5. Дождитесь результата проверки, затем протестируйте функцию, использующую провайдера.

Make Agent Fast выполняет живой запрос проверки перед пометкой ключа активным. Ключ не должен содержать пробелов или переносов строк и должен быть от 16 до 512 символов. Ключи Anthropic должны начинаться с `sk-ant-`; ключи OpenAI — с `sk-`. У других провайдеров нет стабильного публичного префикса, поэтому живая проверка авторитетна.

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

## Как работает выбор текстового провайдера [#как-работает-выбор-текстового-провайдера]

Для генерации текста Make Agent Fast сначала ищет активный ключ BYOK, совпадающий с настроенным текстовым провайдером платформы. Если его нет, проверяет активные ключи Anthropic, OpenAI и Gemini в этом порядке. Если подходящего ключа BYOK нет, использует провайдера платформы, когда тариф и развёртывание позволяют.

Ключи речи специфичны для провайдера. Ключ Deepgram используется только когда активный провайдер речи-в-текст — Deepgram; ключ ElevenLabs используется только когда синтез речи или клонирование настроены для ElevenLabs.

Ключи BYOK сейчас не заменяют учётные данные эмбеддинга знаний платформы. Приём и поиск знаний продолжают использовать настроенного провайдера эмбеддингов развёртывания.

## Оплата и кредиты [#оплата-и-кредиты]

* Внешний провайдер списывает использование с аккаунта, выдавшего ключ.
* Make Agent Fast по-прежнему списывает часть подписки и инфраструктуры поддерживаемой работы BYOK.
* Текстовые запросы BYOK обычно используют уменьшенный счётчик инфраструктуры вместо полного счётчика стоимости модели.
* Работа голоса может сохранять минимумы конвейера речи, потому что захват, транскрибация, синтез, доставка и оркестрация — отдельные стадии.
* Исчерпание квоты провайдера может отклонить запрос даже при оставшихся кредитах Make Agent Fast.

Проверяйте и **Использование и кредиты** в Make Agent Fast, и собственную панель использования провайдера.

## Состояния ключей и обработка сбоев [#состояния-ключей-и-обработка-сбоев]

| Состояние | Значение                                            | Что делать                                                                                 |
| --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `active`  | Живая проверка успешна                              | Протестируйте целевую функцию и следите за использованием провайдера                       |
| `invalid` | Проверка не прошла или провайдер позже отклонил его | Проверьте оплату, ограничения, квоту и состояние отзыва провайдера; затем сохраните замену |
| `revoked` | Ключ отключён в Make Agent Fast                     | Создайте или активируйте замену, если функция должна продолжать использовать BYOK          |

Если запрос не работает, потому что провайдер отклоняет учётные данные или квоту, Make Agent Fast может пометить хранимый ключ недействительным. Исправление ключа у провайдера не раскрывает и не переписывает хранимый секрет; сохраните рабочий ключ снова для повторной проверки.

## Ротируйте ключ провайдера [#ротируйте-ключ-провайдера]

1. Создайте новый ключ провайдера, не удаляя старый.
2. Сохраните новый ключ в Make Agent Fast и подтвердите, что он стал активным.
3. Протестируйте текстовый чат, голосовые сообщения или клонирование — что использует этого провайдера.
4. Отзовите старый ключ в консоли провайдера.
5. Проверьте логи провайдера на неожиданное использование старого ключа.

Если ключ раскрыт в системе контроля версий или браузерном коде, немедленно отзовите его у провайдера. Его удаление только из Make Agent Fast не останавливает другого держателя от прямого использования с провайдером.

---

# Безопасность

Source: /ru/docs/account/security.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Учётные данные&#x22;, description: &#x22;Ключи, секреты OAuth и токены коннекторов остаются на стороне сервера.&#x22; },
{ icon: &#x22;embed&#x22;, title: &#x22;Разрешённые списки встраивания&#x22;, description: &#x22;Управляйте, какие origin могут загружать ваш виджет агента.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;Вебхуки&#x22;, description: &#x22;Проверяйте подписи перед доверием входящим событиям.&#x22; }
]"
/>

## Доступ к аккаунту [#доступ-к-аккаунту]

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

Подтвердите электронный адрес аккаунта по ссылке, отправленной после регистрации. Аккаунты с паролем могут использовать **Забыли пароль** на странице входа; успешный сброс отзывает существующие сессии. **Настройки аккаунта** могут менять локальный пароль, явно привязывать Google при включении и выходить со всех устройств. Аккаунты только с OAuth не имеют локального пароля для смены, и обычный вход никогда не привязывает молча новую идентичность.

## Секреты [#секреты]

Ключи API, токены коннекторов, секреты приложений, секреты вебхуков и ключи голосовых провайдеров — учётные данные. Храните их в утверждённом менеджере секретов, никогда в клиентском коде, и ротируйте после раскрытия.

## Минимальные права [#минимальные-права]

Выбирайте узкие области API, выделенные приложения внешних платформ, точные origin встраивания и отдельные ключи для отдельных систем. Удаляйте неиспользуемые учётные данные и интеграции.

## Контент и приватность [#контент-и-приватность]

Загружайте только данные, которые агенту разрешено использовать. Тестируйте отказы и пути эскалации и применяйте правила хранения к экспортам диалогов и заявок.

## Отчётность [#отчётность]

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

---

# Решение проблем

Source: /ru/docs/account/troubleshooting.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Публикация&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;Встраивание&#x22;, icon: &#x22;embed&#x22; }, { label: &#x22;Коннекторы&#x22;, icon: &#x22;connectors&#x22; }]" />

## Начните с воспроизводимого случая [#начните-с-воспроизводимого-случая]

Перед изменением настроек зафиксируйте:

* Рабочее пространство/сайт, публичный маршрут или конечную точку API и точное время с часовым поясом.
* Ожидаемый результат и фактический результат.
* Браузер/устройство или канал внешнего провайдера.
* Затрагивает ли сбой предпросмотр владельца, оставшуюся размещённую демо-страницу, встраивание, коннектор и/или API.
* Безопасный текст статуса/ошибки, `x-request-id` ответа, последнюю ошибку коннектора или ID события доставки провайдера.
* Последнее известное рабочее время и наименьшее недавнее изменение.

Не включайте учётные данные API/провайдера/коннектора в открытом виде, секреты вебхуков, приватные данные клиентов, полные заголовки авторизации или ненужное содержимое диалогов.

## Изменения сайта не появляются [#изменения-сайта-не-появляются]

1. Убедитесь, что URL панели принадлежит нужному сайту и рабочему пространству.
2. Убедитесь, что действие сохранения сообщило об успехе.
3. Для текста страницы, знаний или характера опубликуйте текущее состояние снова из **Проверка и публикация**.
4. Для **Внешнего вида** (и значка брендинга) успешное сохранение уже обновляет живое встраивание — пропустите повторную публикацию и откройте приватное окно.
5. Откройте реальное встраивание (или оставшийся размещённый slug, если он у вас есть) в приватном окне.
6. Если устарел только социальный предпросмотр, используйте кэш/отладчик этой платформы.

Отмена публикации и редактирование — разные вещи. Подключённый коннектор сообщений может продолжать отвечать даже при выключенном встраивании.

## Ответ агента слабый или неверный [#ответ-агента-слабый-или-неверный]

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

Когда в источнике нет ответа, улучшите поведение запасного ответа/эскалации вместо инструктирования агента угадывать. Используйте [Источники знаний](/ru/docs/build/knowledge) для создания приёмочного набора прямой/перефразировка/граница.

## Загрузчик встраивания отсутствует или заблокирован [#загрузчик-встраивания-отсутствует-или-заблокирован]

Убедитесь, что сайт опубликован, встраивание включено, скрипт имеет точный slug сайта и финальный родительский origin браузера — включая схему, имя хоста и порт — в разрешённом списке. В DevTools изучите запрос `embed.js`, ошибки CSP, состояние менеджера согласия, запрос iframe и наличие одного корня `data-maf-embed`.

Если текст работает, а микрофон нет, проверьте HTTPS, разрешение браузера, разрешение iframe allow и Permissions Policy сайта. Следуйте полному [Обзору встраивания](/ru/docs/embed/overview) и [Безопасности и CSP](/ru/docs/embed/security).

## Голос не работает [#голос-не-работает]

Разделите сбоящий режим: голосовое сообщение, живой звонок, клон или голос коннектора. Работающий путь текста доказывает только ключ языковой модели.

Проверяйте ключи провайдеров транскрибации, TTS, реального времени и клонирования независимо; затем проверьте право тарифа, баланс кредитов, лимит живых минут, разрешение браузера, настроенные языки, лимиты образцов и согласие. Протестируйте короткую чистую запись перед исследованием длинного/шумного файла.

## Коннектор не получает сообщений [#коннектор-не-получает-сообщений]

Используйте гайд канала и сравните обе стороны. Убедитесь, что коннектор включён, учётные данные всё ещё проходят проверку, URL вебхука/взаимодействия/скилла провайдера актуален, требуемое событие/Страница/номер/блок подписаны, режим приложения включает тестового пользователя и публичная HTTPS доставка успешна.

Успех проверки вебхука не доказывает подписку на события во время работы или исходящие разрешения. Сравнивайте логи доставки провайдера с **Последним сообщением** и сохранённой ошибкой коннектора. Тестируйте текст перед голосом.

## Собственные домены не предлагаются [#собственные-домены-не-предлагаются]

Мы не продаём и не привязываем домены клиентов. Разместите агента на сайте, который у вас уже есть, через [встраивание](/ru/docs/embed/overview). Оставшиеся события дополнения доменов Polar игнорируются или отменяются и никогда не начисляют кредиты.

## Запрос API не работает [#запрос-api-не-работает]

Запишите метод, версионный путь, статус, стабильный код ошибки, `x-request-id` ответа и релевантные заголовки лимита частоты. Затем классифицируйте:

| Статус | Наиболее вероятное действие                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `400`  | Исправьте форму JSON/формы или детали валидации; не повторяйте без изменений                            |
| `401`  | Используйте валидные неистёкшие/неотозванные учётные данные MAF; никогда не используйте ключ провайдера |
| `403`  | Добавьте требуемую область или восстановите доступ к тарифу/ресурсу                                     |
| `404`  | Убедитесь, что ID принадлежит аутентифицированному рабочему пространству и путь правильный              |
| `409`  | Разрешите конфликт состояния или повторите тот же ключ идемпотентности/полезную нагрузку                |
| `415`  | Отправьте задокументированный тип контента                                                              |
| `429`  | Соблюдайте заголовки `retry-after`/сброса с джиттером; не зацикливайтесь                                |
| `500`  | Повторите безопасный/идемпотентный запрос и сохраните ID запроса/время                                  |

Используйте [Учётные данные и токены](/ru/docs/api/credentials), [Области и ошибки](/ru/docs/api/scopes-errors) и [Лимиты частоты](/ru/docs/api/rate-limits). Никогда не решайте ошибку API перемещением серверных учётных данных в браузерный код.

## Оплата или использование выглядит неправильно [#оплата-или-использование-выглядит-неправильно]

Различайте доступ платформы, ежемесячные кредиты, купленные кредиты, число сайтов, живые минуты, слоты клонов, частоту API, каналы сообщений (Operate+) и BYOK/команду (Scale). Пополнение меняет только кредиты. Списания провайдера BYOK отделены от оплаты Make Agent Fast.

При неожиданном использовании изолируйте вероятный источник перед исследованием: отключите коннектор, отзовите ключ, удалите непредназначенный origin встраивания или остановите цикл повторов API. Сохраняйте диапазон времени и ID запросов/провайдеров без раскрытия секретов.

## Соберите безопасные детали для поддержки [#соберите-безопасные-детали-для-поддержки]

Если всё ещё заблокированы, используйте элемент обратной связи на наиболее релевантном гайде или обратитесь в поддержку из панели с:

* Идентификатором сайта/рабочего пространства и затронутой функцией.
* Точной временной меткой/часовым поясом и воспроизводимыми шагами.
* Ожидаемым и фактическим результатом.
* Публичным несекретным URL, когда релевантно.
* HTTP статусом, стабильным кодом ошибки, `x-request-id` или ID события провайдера.
* Отредактированным скриншотом или минимальной полезной нагрузкой с удалёнными секретами и персональными данными.

Укажите, что вы уже проверили. Это предотвращает повторные советы по настройке и проясняет границу сбоя.

---

# Аутентификация

Source: /ru/docs/api/authentication.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Ключи API&#x22;, description: &#x22;Учётные данные bearer с областями для одного аккаунта и контролируемого вами сервера.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;OAuth&#x22;, description: &#x22;Проверенная авторизация для приложений, подключающих несколько клиентских аккаунтов.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Минимальные права&#x22;, description: &#x22;Каждая операция называет точную область чтения или записи, которая ей нужна.&#x22; }
]"
/>

Используйте ключ API для вашего собственного бэкенда или автоматизации. Используйте OAuth, когда ваше приложение просит других пользователей Make Agent Fast предоставить доступ. Оба типа учётных данных вызывают те же ресурсы `/api/v1` и подчиняются тем же областям, правам тарифа, изоляции арендаторов и лимитам частоты.

## Ключи API [#ключи-api]

Активный платный тариф требуется для создания и использования публичного ключа API.

1. Откройте **Панель → Настройки → Разработчик**.
2. Введите имя, идентифицирующее сервис и окружение, например `Production lead export`.
3. Выберите минимальные области, нужные сервису.
4. Выберите срок: 30 дней, 90 дней, один год или никогда.
5. Создайте ключ и немедленно скопируйте значение `maf_live_...`.

Make Agent Fast хранит хеш SHA-256 вместо восстанавливаемого открытого текста. Панель позже показывает безопасный префикс, области, срок, время последнего использования и состояние отзыва.

```http
Authorization: Bearer maf_live_...
```

Отправляйте заголовок из серверного кода:

```bash
curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Отсутствующие учётные данные возвращают `401 authentication_required`. Недействительные, истёкшие или отозванные ключи возвращают `401 invalid_api_key`. Ключ, чей аккаунт больше не имеет активного платного тарифа, возвращает `403 subscription_required`.

### Ротируйте или отзовите ключ [#ротируйте-или-отзовите-ключ]

Создайте замену перед отзывом старого ключа. Разверните замену, сделайте реальный запрос, проверьте его `x-request-id`, затем нажмите **Отозвать** на старом ключе. Отзыв мгновенен и не может быть отменён.

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

## OAuth-приложения [#oauth-приложения]

OAuth — для ПО, подключающего аккаунты, принадлежащие другим пользователям Make Agent Fast. Он использует Authorization Code с PKCE (`S256`) и не выдаёт и не требует секрет клиента. ID клиента публичен; коды авторизации, токены доступа, токены обновления и верификатор PKCE чувствительны.

### 1. Зарегистрируйте приложение [#1-зарегистрируйте-приложение]

Откройте **Панель → Настройки → Разработчик → OAuth-приложения**. Добавьте:

* Имя приложения от 2 до 100 символов.
* От 1 до 10 точных URL перенаправления.
* Максимальные области, которые ваше приложение может запрашивать.

Продакшен URL перенаправления должны использовать HTTPS и не могут содержать учётные данные или фрагменты. Полный URI должен совпадать с зарегистрированным значением во время авторизации и обмена токенов. Недавно отправленные приложения имеют статус `pending`; авторизация работает только после того, как приложение проверено и помечено `approved`.

Владелец платформы проверяет ожидающие ID клиентов аудируемым процессом
`oauth:review`. Сохраните ID клиента, показанный после отправки; его статус
виден на странице Разработчика, и отклонённые приложения включают решение
проверки перед возможностью повторной отправки.

### 2. Сгенерируйте значения PKCE [#2-сгенерируйте-значения-pkce]

Генерируйте новый верификатор для каждой попытки авторизации и держите его в той же защищённой короткоживущей сессии, что и `state`.

```ts
import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
```

Верификатор должен содержать 43–128 URL-безопасных символов PKCE. Принимается только `code_challenge_method=S256`.

### 3. Перенаправьте пользователя для согласия [#3-перенаправьте-пользователя-для-согласия]

```text
https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
```

Пользователь входит, проверяет запрошенные области и разрешает или отказывает в доступе. При успехе Make Agent Fast перенаправляет на точный зарегистрированный URI с `code` и исходным `state`. При отказе отправляет `error=access_denied` и исходный `state`, когда он был предоставлен.

Отклоняйте обратный вызов, если `state` не совпадает точно со значением, сохранённым для этой браузерной сессии.

### 4. Обменяйте код авторизации [#4-обменяйте-код-авторизации]

Код авторизации истекает через 10 минут и может быть использован только один раз.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"
```

```json
{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}
```

Токен доступа длится один час. Токен обновления длится до 90 дней, если он не ротирован или отозван раньше.

### 5. Ротируйте токен обновления [#5-ротируйте-токен-обновления]

Каждое успешное обновление отзывает и отправленный токен обновления, и его предыдущий токен доступа, затем возвращает новую пару. Сохраняйте новую пару атомарно перед отбрасыванием состояния предыдущего ответа.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
```

Повторное использование кода авторизации или ротированного токена обновления возвращает `invalid_grant`. Конечная точка токенов OAuth возвращает ответы в стиле OAuth `{ "error", "error_description" }` вместо оболочки ошибок публичного API и разрешает 30 запросов токенов на клиента и вызывающего в минуту.

## Никогда не аутентифицируйте запросы управления в браузерном коде [#никогда-не-аутентифицируйте-запросы-управления-в-браузерном-коде]

Не помещайте секретный ключ API, токен доступа или токен обновления в клиентские компоненты React, статический JavaScript, мобильный веб, Webflow, Framer, Wix или Shopify Liquid. Используйте ваш аутентифицированный бэкенд. Публичное встраивание сайта использует несекретный slug сайта и разрешённый список origin, а не учётные данные управления API.

См. [Учётные данные и токены](/ru/docs/api/credentials), [Области и ошибки](/ru/docs/api/scopes-errors) и [Быстрый старт API](/ru/docs/api/quickstart).

---

# Учётные данные и токены

Source: /ru/docs/api/credentials.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Серверные учётные данные&#x22;, description: &#x22;Ключи API и токены OAuth авторизуют доступ к публичному API.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Учётные данные каналов&#x22;, description: &#x22;Токены ботов и секреты приложений подключают внешних провайдеров сообщений.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Ключи провайдеров&#x22;, description: &#x22;Учётные данные BYOK оплачивают AI-провайдеров с вашего собственного аккаунта провайдера.&#x22; }
]"
/>

Make Agent Fast использует несколько типов учётных данных. Они не взаимозаменяемы. Перед копированием значения определите, какая система его выдала, какая система его получает и безопасно ли его раскрывать в браузере.

## Карта учётных данных [#карта-учётных-данных]

| Учётные данные                         | Создаются в                                        | Используются                        | Секрет? | Типичный формат или значение                    |
| -------------------------------------- | -------------------------------------------------- | ----------------------------------- | ------- | ----------------------------------------------- |
| Slug опубликованного сайта             | Панель сайта                                       | Загрузчик встраивания сайта         | Нет     | `my-agent`                                      |
| Ключ Make Agent Fast API               | **Настройки → Разработчик**                        | Ваш бэкенд или автоматизация        | Да      | `maf_live_...`                                  |
| ID клиента OAuth                       | **Настройки → Разработчик**                        | Приложение для нескольких аккаунтов | Нет     | `maf_app_...`                                   |
| Токен доступа OAuth                    | Конечная точка токенов OAuth                       | Бэкенд вашего приложения            | Да      | Токен Bearer, час жизни                         |
| Токен обновления OAuth                 | Конечная точка токенов OAuth                       | Ваше безопасное хранилище токенов   | Да      | `maf_refresh_...`, ротируется при использовании |
| Ключ AI-провайдера                     | Anthropic, OpenAI, Google, Deepgram или ElevenLabs | Бэкенд Make Agent Fast              | Да      | Специфичен для провайдера                       |
| Токен коннектора или секрет приложения | Telegram, Meta, Discord или Kakao                  | Сервис коннекторов Make Agent Fast  | Да      | Специфичен для провайдера                       |
| Секрет подписи вебхука                 | Создание конечной точки вебхука публичного API     | Ваш приёмник вебхуков               | Да      | `whsec_...`                                     |

<Callout title="Встраивание сайта не использует ключ API">
  Загрузчику встраивания нужны публичный slug сайта и разрешённый origin сайта. Никогда не добавляйте ключ Make Agent Fast API, ключ провайдера, токен коннектора или секрет вебхука в тег скрипта.
</Callout>

## Выберите правильный метод авторизации [#выберите-правильный-метод-авторизации]

Используйте **ключ Make Agent Fast API** для контролируемого вами сервера и одного аккаунта Make Agent Fast. Выбирайте только области, нужные этому серверу.

Используйте **OAuth Authorization Code с PKCE**, когда ваш продукт подключает аккаунты, принадлежащие другим пользователям Make Agent Fast. OAuth-приложения требуют проверки перед успешной продакшен-авторизацией.

Используйте **ключ AI-провайдера** только когда хотите, чтобы Make Agent Fast вызывал этого AI-провайдера с вашего аккаунта провайдера. Ключ провайдера не авторизует публичный API Make Agent Fast.

Используйте **учётные данные коннектора** только в соответствующей форме коннектора или запросе API коннектора. Токен бота Telegram не может авторизовать запросы Discord, Meta или Make Agent Fast API.

## Храните секреты безопасно [#храните-секреты-безопасно]

Для локальной разработки помещайте секреты в игнорируемый файл окружения или ваше окружение shell:

```bash
export MAF_API_KEY="maf_live_..."
```

Для развёртывания используйте зашифрованный менеджер секретов хостинг-провайдера. Не помещайте секреты в:

* Коммиты Git, описания задач, скриншоты, свойства аналитики или сообщения поддержки.
* `NEXT_PUBLIC_*`, `VITE_*` или другие переменные, встроенные в браузерный JavaScript.
* Webflow, Framer, Wix, Shopify Liquid, WordPress HTML или бандл мобильного веба.
* Строки запроса. URL обычно сохраняются в истории браузера, прокси и логах.

Делайте вызовы API через ваш аутентифицированный бэкенд. Браузер должен вызывать ваш бэкенд, а ваш бэкенд должен прикреплять секрет.

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites", {
  headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
```

## Правила одноразовых секретов [#правила-одноразовых-секретов]

Ключи API, секреты подписи вебхуков и новые выданные токены обновления OAuth должны копироваться при показе. Полное значение в открытом виде не может быть восстановлено позже. Если оно потеряно, создайте замену вместо просьбы поддержки раскрыть его.

Учётные данные AI-провайдеров и коннекторов шифруются перед хранением и не возвращаются через API списков. Панель может показывать метку, префикс, последние четыре символа, состояние проверки или время последнего использования, чтобы вы могли идентифицировать учётные данные без их раскрытия.

## Чек-лист ротации [#чек-лист-ротации]

1. Создайте замену с теми же минимальными областями или разрешениями провайдера.
2. Обновляйте одно развёртывание или приёмник за раз.
3. Проверьте, что реальный запрос успешен, и запишите его `x-request-id`.
4. Отзовите старые учётные данные.
5. Убедитесь, что старые запросы не работают с `401 invalid_api_key` или эквивалентом провайдера.

Для OAuth сохраняйте новый токен обновления, возвращаемый каждым ответом обновления, перед отбрасыванием предыдущего токена. Для ротации секрета вебхука запускайте старую и новую конечные точки параллельно, пока каждый производитель и приёмник не перейдёт на замену.

## Если секрет раскрыт [#если-секрет-раскрыт]

Отзовите или ротируйте его немедленно. Его удаление из последнего коммита Git недостаточно, потому что он может остаться в истории, кэшах, логах или форках. Проверьте активность и в Make Agent Fast, и у выдавшего провайдера, затем замените любые учётные данные, разделявшие то же место хранения или окружение развёртывания.

Продолжите с [Аутентификацией](/ru/docs/api/authentication), [Областями и ошибками](/ru/docs/api/scopes-errors) или [Ключами AI-провайдеров](/ru/docs/account/provider-keys).

---

# Обзор API

Source: /ru/docs/api/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/api/authentication&#x22;, label: &#x22;Аутентификация&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/ru/docs/api/quickstart&#x22;, label: &#x22;Быстрый старт&#x22;, icon: &#x22;bolt&#x22; },
{ href: &#x22;/ru/docs/api/reference&#x22;, label: &#x22;Справочник&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ru/docs/api/webhooks&#x22;, label: &#x22;Вебхуки&#x22;, icon: &#x22;link&#x22; },
{ href: &#x22;/ru/docs/api/sdks&#x22;, label: &#x22;SDK&#x22;, icon: &#x22;code&#x22; }
]"
/>

Публичный API использует ресурсо-ориентированный JSON поверх HTTPS под `/api/v1`. Он доступен на платных тарифах и использует те же права на сайты, кредиты и функции, что и панель.

## Что можно автоматизировать [#что-можно-автоматизировать]

* Сайты и состояние публикации
* Конфигурация агентов, FAQ, товары и знания
* Диалоги, заявки, аналитика, уведомления и рассылки
* Создание заявок и согласие, воронки возможностей, результаты CRM и восстановление синхронизации
* Домены, коннекторы, монетизация, использование и информация аккаунта
* Подписанные подписки вебхуков для поддерживаемых событий

Чувствительные действия используют явные конечные точки действий вместо неограниченной мутации базы данных. Секреты коннекторов принимаются на запись, но никогда не возвращаются.

Это **API управления и синхронизации**. Он может создавать и обновлять заявки,
принимать их в воронку возможностей, импортировать результаты CRM с атрибуцией
источника выиграно/проиграно и повторять неудачные импорты результатов. Отправка
чата посетителя и ответ владельца остаются операциями виджета/панели; аналитика
и использование остаются только для чтения.

## Начните безопасно [#начните-безопасно]

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

```bash
curl https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer maf_live_YOUR_KEY"
```

См. [Аутентификацию](/ru/docs/api/authentication), [Быстрый старт API](/ru/docs/api/quickstart) и [Справочник API](/ru/docs/api/reference).

---

# Быстрый старт API

Source: /ru/docs/api/quickstart.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;10 минут&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Только сервер&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;REST&#x22;, icon: &#x22;code&#x22; }]" />

Этот быстрый старт проверяет, что бэкенд может аутентифицироваться и читать ваш аккаунт. Вам нужен активный платный тариф, терминал с `curl` и доступ к **Панель → Настройки → Разработчик**.

Текущий API v1 управляет и синхронизирует ресурсы. Это не транспорт
пользовательского чата: конечные точки диалогов и заявок только для чтения.

## 1. Создайте ключ с минимальными правами [#1-создайте-ключ-с-минимальными-правами]

Создайте ключ с именем `Local API quickstart`, выберите `account:read` и `sites:read` и выберите короткий срок. Скопируйте ключ в открытом виде немедленно; он не будет показан снова.

Не используйте ключ провайдера от OpenAI, Anthropic, Gemini, Deepgram или ElevenLabs. Публичный API требует ключ Make Agent Fast, начинающийся с `maf_live_`.

## 2. Сохраните его для этого терминала [#2-сохраните-его-для-этого-терминала]

```bash
export MAF_API_KEY="maf_live_..."
```

Подтвердите, что переменная существует, не печатая секрет:

```bash
test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"
```

Не коммитьте ключ в `.env`, примеры истории shell, тестовые фикстуры или браузерный бандл. Для развёрнутого кода используйте менеджер секретов хоста.

## 3. Изучите аккаунт [#3-изучите-аккаунт]

```bash
curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Ожидаемый статус: `200 OK`. Тело содержит `data.id`, информацию тарифа и прав и сводку кошелька. Ответ также содержит `x-request-id`; сохраняйте это значение при сообщении о неудачном запросе.

```json
{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}
```

Поля могут добавляться без изменения пути `/v1`. Игнорируйте неизвестные поля вместо отклонения ответа.

## 4. Перечислите сайты [#4-перечислите-сайты]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Ответы коллекций используют эту оболочку:

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Если `has_more` истинно, отправьте точное значение `next_cursor` как параметр запроса `cursor` следующего запроса. Не декодируйте и не конструируйте курсоры.

## 5. Обработайте структурированную ошибку [#5-обработайте-структурированную-ошибку]

Временно уберите заголовок Authorization и повторите `/me`. Ответ должен быть `401` со стабильным кодом:

```json
{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}
```

Продакшен-код должен ветвиться на `error.code`, а не сравнивать `message`. Логируйте операцию, HTTP статус и ID запроса без логирования ключа.

## 6. Сделайте первую запись безопасно [#6-сделайте-первую-запись-безопасно]

Создайте отдельный ключ, который также имеет `sites:write`, `agents:write` и `knowledge:write`; не расширяйте ключ чтения быстрого старта. Следуйте [Рецептам API](/ru/docs/api/recipes), чтобы создать сайт, добавить обоснованные знания и опубликовать его с явными ключами идемпотентности.

## Частые сбои первого запроса [#частые-сбои-первого-запроса]

| Результат                     | Причина                                                                  | Решение                                                    |
| ----------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `401 authentication_required` | Заголовок отсутствует или не `Bearer TOKEN`                              | Добавьте точный заголовок Authorization из серверного кода |
| `401 invalid_api_key`         | Опечатка, истёкший ключ, отозванный ключ или неверный тип учётных данных | Создайте и скопируйте новый ключ Make Agent Fast API       |
| `403 subscription_required`   | Нет активного платного тарифа                                            | Восстановите подписку аккаунта                             |
| `403 insufficient_scope`      | Ключ не включает область операции                                        | Создайте замену с минимальной недостающей областью         |
| `403 account_paused`          | Доступ API приостановлен для этого аккаунта                              | Возобновите доступ API или свяжитесь с владельцем аккаунта |
| `429 rate_limit_exceeded`     | Минутная корзина ключа исчерпана                                         | Дождитесь `Retry-After` и уменьшите параллелизм            |

Продолжите с [Областями и ошибками](/ru/docs/api/scopes-errors), [Справочником API](/ru/docs/api/reference) и [Лимитами частоты](/ru/docs/api/rate-limits).

---

# Лимиты частоты

Source: /ru/docs/api/rate-limits.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;На ключ&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Одна минута&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Retry-After&#x22;, icon: &#x22;code&#x22; }]" />

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

## Лимиты тарифов [#лимиты-тарифов]

| Активный тариф | Запросов на ключ в минуту |
| -------------- | ------------------------: |
| Launch         |                       120 |
| Operate        |                       600 |
| Scale          |                     1 800 |

Учётные данные, чей аккаунт не имеет активного платного тарифа, получают `403 subscription_required` до предоставления ёмкости лимита частоты. Make Agent Fast может ввести более низкие специфичные для конечной точки лимиты для необычно дорогих операций; когда это происходит, справочник конечной точки указывает их явно.

## Ответ с ограничением частоты [#ответ-с-ограничением-частоты]

Когда корзина исчерпана, API возвращает `429 rate_limit_exceeded` с:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json
```

`Retry-After` — минимальное число секунд ожидания. Каждый аутентифицированный
ответ также включает `X-RateLimit-Limit`, `X-RateLimit-Remaining` и
`X-RateLimit-Reset` (временная метка Unix), так что приложения могут замедляться
до `429`.

## Реализация повтора [#реализация-повтора]

Используйте экспоненциальный откат со случайным джиттером, соблюдайте больший `Retry-After` и ограничивайте общее число попыток.

```ts
async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}
```

Для `POST`, `PATCH` и `DELETE` сохраняйте один валидный `Idempotency-Key` на каждом сетевом или серверном повторе. Новый ключ идемпотентности может повторить завершённый побочный эффект.

## Уменьшите объём запросов [#уменьшите-объём-запросов]

* Кэшируйте чтения аккаунта, сайта и конфигурации, которым не нужна свежесть реального времени.
* Запрашивайте до `100` записей на страницу вместо повторных запросов очень малых страниц.
* Обрабатывайте события вебхуков вместо опроса диалогов, заявок, состояния доменов или рассылок.
* Ограничивайте параллелизм воркеров на ключ API; всплеск от многих бессерверных вызовов разделяет одну корзину.
* Используйте отдельные ключи для отдельных сервисов ради изоляции и аудируемости, а не для умножения ёмкости одной нагрузки.

## Таблица повторов и не-повторов [#таблица-повторов-и-не-повторов]

| Ответ                             | Повторять? | Условие                                                                          |
| --------------------------------- | ---------- | -------------------------------------------------------------------------------- |
| `429`                             | Да         | Дождитесь `Retry-After`, добавьте джиттер и ограничьте попытки                   |
| `500`                             | Иногда     | Безопасные чтения или мутации, защищённые тем же ключом идемпотентности          |
| Конфликт обработки `409`          | Да         | Дождитесь его заголовка `Retry-After: 2` и сохраните тот же ключ идемпотентности |
| Другой `409`                      | Не сразу   | Прочитайте текущее состояние ресурса и разрешите конфликт                        |
| `400`, `401`, `403`, `404`, `415` | Нет        | Сначала исправьте ввод, учётные данные, право, путь или тип контента             |

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

---

# Рецепты API

Source: /ru/docs/api/recipes.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Создать&#x22;, icon: &#x22;site&#x22; }, { label: &#x22;Обосновать&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Опубликовать&#x22;, icon: &#x22;globe&#x22; }]" />

Эти рецепты используют сырой REST, чтобы работать до установки публичного SDK. Установите `MAF_API_KEY` в окружении сервера и заменяйте ID, возвращённые более ранними шагами.

## Рецепт: создать и опубликовать обоснованного агента [#рецепт-создать-и-опубликовать-обоснованного-агента]

Создайте один ключ API с `sites:write`, `agents:write` и `knowledge:write`. Добавьте `sites:read`, если автоматизация также перечисляет или проверяет сайты.

### 1. Создайте сайт [#1-создайте-сайт]

```bash
curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support",
      "subheadline": "Answers grounded in our current policies.",
      "about": "Acme support answers product and account questions."
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'
```

Успешный ответ — `201 Created`, включает сайт под `data` и возвращает его канонический путь ресурса в заголовке `Location`. Сохраните `data.id` как `SITE_ID`.

### 2. Настройте агента и политику встраивания [#2-настройте-агента-и-политику-встраивания]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'
```

Разрешённые origin — точные origin: схема, имя хоста и опциональный порт. Не включайте путь или завершающий шаблон.

### 3. Добавьте текстовый источник знаний [#3-добавьте-текстовый-источник-знаний]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'
```

Публичный API сейчас принимает вставленный текст от 5 до 200 000 символов. Используйте панель для сканирования URL, загрузок, YouTube, подкастов и лент.

### 4. Добавьте структурированный FAQ [#4-добавьте-структурированный-faq]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'
```

### 5. Опубликуйте [#5-опубликуйте]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'
```

Ответ должен содержать `{"data":{"id":"...","status":"published"}}`. Откройте реальное встраивание и задайте вопрос, ответ на который есть в источнике. Публикация доказывает, что состояние агента изменилось; она не доказывает, что качество источника или origin встраивания правильные.

## Рецепт: безопасная пагинация заявок [#рецепт-безопасная-пагинация-заявок]

Используйте ключ с `leads:read`. Относитесь к `next_cursor` как к непрозрачному и URL-кодируйте его.

```ts
const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);
```

Не декодируйте, не редактируйте, не сортируйте и не используйте повторно курсор для другой коллекции.

## Рецепт: отключить встраивание во время инцидента [#рецепт-отключить-встраивание-во-время-инцидента]

Используйте `agents:write` и сохраняйте тот же ключ идемпотентности на сетевых повторах:

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'
```

После успеха ответа проверьте, что загрузчик больше не инициализируется на разрешённом хосте. Включите его снова новым ключом разрешения инцидента после исправления проблемы origin, контента или учётных данных.

## Продакшен-чек-лист [#продакшен-чек-лист]

* Используйте отдельный ключ на сервис и окружение.
* Сохраняйте ID ресурсов и ключи идемпотентности перед отправкой мутации.
* Устанавливайте таймауты соединения и ответа.
* Соблюдайте `Retry-After` и ограничивайте повторы.
* Логируйте имя операции, HTTP статус и ID запроса без логирования секретов или персональных данных.
* Тестируйте против непродакшен-сайта перед предоставлением областей записи продакшену.

---

# Справочник API

Source: /ru/docs/api/reference.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;v1&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;60 операций&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;JSON&#x22;, icon: &#x22;book&#x22; }]" />

Канонический машиночитаемый контракт — [OpenAPI JSON](/api/openapi.json). Эта страница — человекочитаемый индекс операций и объясняет правила, общие для каждой конечной точки.

## Базовый URL и версия [#базовый-url-и-версия]

```text
https://makeagent.fast/api/v1
```

Мажорная версия — часть пути. Добавочные поля могут появляться без смены мажорной версии, поэтому игнорируйте неизвестные поля ответа. Все запросы управления используют HTTPS и ключ API bearer или токен доступа OAuth.

## Общие заголовки [#общие-заголовки]

```http
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key
```

`Content-Type` обязателен для тел JSON `POST` и `PATCH`, включая `{}`. `Idempotency-Key` опционален, но настоятельно рекомендуется для каждого `POST`, `PATCH` и `DELETE`.

## Аккаунт и сайты [#аккаунт-и-сайты]

| Метод    | Путь                       | Область        | Назначение                                                                    |
| -------- | -------------------------- | -------------- | ----------------------------------------------------------------------------- |
| `GET`    | `/me`                      | `account:read` | Читать аккаунт, тариф, права и сводку кошелька                                |
| `GET`    | `/sites`                   | `sites:read`   | Перечислить принадлежащие сайты                                               |
| `POST`   | `/sites`                   | `sites:write`  | Создать сайт и его агента по умолчанию                                        |
| `GET`    | `/sites/{site_id}`         | `sites:read`   | Получить один принадлежащий сайт                                              |
| `PATCH`  | `/sites/{site_id}`         | `sites:write`  | Обновить безопасные поля сайта                                                |
| `DELETE` | `/sites/{site_id}`         | `sites:write`  | Удалить сайт и зависимые ресурсы                                              |
| `POST`   | `/sites/{site_id}/publish` | `sites:write`  | Опубликовать или отменить публикацию с `{ "published": boolean }`             |
| `GET`    | `/sites/{site_id}/agent`   | `agents:read`  | Читать настройки агента                                                       |
| `PATCH`  | `/sites/{site_id}/agent`   | `agents:write` | Обновить характер, инструкции, голос, языки, состояние встраивания или origin |

Создание сайта требует `title` и `content.headline`. Опциональные поля включают `slug`, `type`, `template`, дополнительный контент, `persona_mode` и от одного до четырёх языков из `en`, `ko`, `uz` и `ru`.

## Знания и FAQ [#знания-и-faq]

| Метод    | Путь                                     | Область           | Назначение                                                         |
| -------- | ---------------------------------------- | ----------------- | ------------------------------------------------------------------ |
| `GET`    | `/sites/{site_id}/knowledge`             | `knowledge:read`  | Перечислить источники знаний                                       |
| `POST`   | `/sites/{site_id}/knowledge`             | `knowledge:write` | Принять `{ "name", "text" }`; текст должен быть 5–200 000 символов |
| `DELETE` | `/sites/{site_id}/knowledge/{source_id}` | `knowledge:write` | Удалить один источник из будущего поиска                           |
| `GET`    | `/sites/{site_id}/faqs`                  | `knowledge:read`  | Перечислить структурированные FAQ                                  |
| `POST`   | `/sites/{site_id}/faqs`                  | `knowledge:write` | Создать `{ "question", "answer", "approved" }`                     |
| `PATCH`  | `/sites/{site_id}/faqs/{faq_id}`         | `knowledge:write` | Обновить вопрос, ответ или состояние утверждения                   |
| `DELETE` | `/sites/{site_id}/faqs/{faq_id}`         | `knowledge:write` | Удалить FAQ                                                        |

Публичный API принимает вставленный текст. Используйте панель для сканирования URL, загрузки файлов, YouTube, подкастов и процессов лент.

## Диалоги, заявки, аналитика и использование [#диалоги-заявки-аналитика-и-использование]

| Метод   | Путь                                               | Область              | Назначение                                                              |
| ------- | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/conversations`                   | `conversations:read` | Перечислить ветки диалогов                                              |
| `GET`   | `/sites/{site_id}/conversations/{conversation_id}` | `conversations:read` | Получить ветку и пагинированные сообщения                               |
| `GET`   | `/sites/{site_id}/leads`                           | `leads:read`         | Перечислить собранные заявки                                            |
| `POST`  | `/sites/{site_id}/leads`                           | `leads:write`        | Создать каноническую заявку с явным согласием и предпочтениями контакта |
| `GET`   | `/sites/{site_id}/leads/{lead_id}`                 | `leads:read`         | Получить одну заявку                                                    |
| `PATCH` | `/sites/{site_id}/leads/{lead_id}`                 | `leads:write`        | Обновить, квалифицировать или изменить политику контакта заявки         |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/accept`          | `leads:write`        | Принять заявку в воронку возможностей                                   |
| `GET`   | `/sites/{site_id}/analytics`                       | `analytics:read`     | Перечислить события аналитики                                           |
| `GET`   | `/sites/{site_id}/usage`                           | `usage:read`         | Перечислить учитываемые события использования                           |

Эти коллекции событий и активностей принимают `limit` и `cursor`. Возвращённые записи могут содержать персональные данные; храните и экспортируйте их согласно вашим обязательствам приватности.

Отправка сообщений посетителей и публикация ответов владельца — не операции
публичного API. Мутация заявок поддерживается; не устанавливайте
`consent_status: granted`, если у вашей системы нет защитимой записи согласия.
Неизвестное согласие исключается из рассылок.

## Воронка возможностей и результаты CRM [#воронка-возможностей-и-результаты-crm]

| Метод           | Путь                                                            | Область                            | Назначение                                                                                       |
| --------------- | --------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/stages`                              | `pipeline:read` / `pipeline:write` | Перечислить или настроить стадии                                                                 |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/accounts`                            | `pipeline:read` / `pipeline:write` | Перечислить или создать бизнес-аккаунты                                                          |
| `GET`           | `/sites/{site_id}/pipeline/accounts/{account_id}`               | `pipeline:read`                    | Получить бизнес-аккаунт                                                                          |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/opportunities`                       | `pipeline:read` / `pipeline:write` | Перечислить или создать возможности                                                              |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline/opportunities/{opportunity_id}`      | `pipeline:read` / `pipeline:write` | Читать активность или обновить назначение, ценность, стадию, следующее действие и ответ человека |
| `POST`          | `/sites/{site_id}/pipeline/outcomes`                            | `pipeline:write`                   | Идемпотентно импортировать результат CRM выиграно или проиграно                                  |
| `GET`           | `/sites/{site_id}/pipeline/sync-records`                        | `pipeline:read`                    | Перечислить статус синхронизации, попытки и ошибки                                               |
| `POST`          | `/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry` | `pipeline:write`                   | Повторить неудачный результат из его хранимой полезной нагрузки                                  |

Предоставленные `provider` CRM, внешний ID и ключ идемпотентности остаются в
аудиторском следе. Повтор захватывает только неудачную запись и никогда не
превращает внешнюю запись в процессе в ложный успех.

## Коннекторы [#коннекторы]

| Метод    | Путь                                          | Область            | Назначение                                                     |
| -------- | --------------------------------------------- | ------------------ | -------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/connectors`                 | `connectors:read`  | Перечислить состояние коннекторов без секретов                 |
| `POST`   | `/sites/{site_id}/connectors`                 | `connectors:write` | Создать или заменить коннектор канала и обеспечить его вебхук  |
| `PATCH`  | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | Установить `status` или `reply_with_voice`                     |
| `DELETE` | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | Деобеспечить и удалить коннектор                               |
| `GET`    | `/sites/{site_id}/domains`                    | `domains:read`     | Удалено — возвращает `409`. Собственные домены не предлагаются |
| `POST`   | `/sites/{site_id}/domains`                    | `domains:write`    | Удалено — возвращает `409`                                     |
| `PATCH`  | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Удалено — возвращает `409`                                     |
| `POST`   | `/sites/{site_id}/domains/{domain_id}/verify` | `domains:write`    | Удалено — возвращает `409`                                     |
| `DELETE` | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Удалено — возвращает `409`                                     |

Создание коннектора использует тело с дискриминацией по каналу. Поля учётных данных различаются для `telegram`, `whatsapp`, `messenger`, `instagram`, `discord` и `kakao`; используйте соответствующий гайд коннектора перед отправкой секретов.

## Рассылки, уведомления и монетизация [#рассылки-уведомления-и-монетизация]

| Метод    | Путь                                                  | Область               | Назначение                                                     |
| -------- | ----------------------------------------------------- | --------------------- | -------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/broadcasts`                         | `broadcasts:read`     | Перечислить рассылки                                           |
| `POST`   | `/sites/{site_id}/broadcasts`                         | `broadcasts:write`    | Создать черновик рассылки Kakao                                |
| `POST`   | `/sites/{site_id}/broadcasts/{broadcast_id}/send`     | `broadcasts:write`    | Поставить в очередь существующий черновик; возвращает `202`    |
| `GET`    | `/sites/{site_id}/notifications`                      | `notifications:read`  | Перечислить уведомления владельца                              |
| `PATCH`  | `/sites/{site_id}/notifications/{notification_id}`    | `notifications:write` | Отметить прочитанным или непрочитанным с `{ "read": boolean }` |
| `GET`    | `/sites/{site_id}/monetization/products`              | `monetization:read`   | Перечислить продукты сайта                                     |
| `POST`   | `/sites/{site_id}/monetization/products`              | `monetization:write`  | Создать продукт доступа, консультации, чаевых или цифровой     |
| `PATCH`  | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Обновить поля продукта и состояние активности                  |
| `DELETE` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Удалить продукт                                                |

Создание рассылки сейчас принимает только канал `kakao`. Постановка в очередь не работает с `409 conflict`, когда нет достижимых получателей или рассылка больше не черновик.

## Вебхуки разработчика [#вебхуки-разработчика]

| Метод    | Путь                               | Область          | Назначение                                                                  |
| -------- | ---------------------------------- | ---------------- | --------------------------------------------------------------------------- |
| `GET`    | `/webhook-endpoints`               | `webhooks:read`  | Перечислить состояние конечных точек без секретов подписи                   |
| `POST`   | `/webhook-endpoints`               | `webhooks:write` | Зарегистрировать публичный HTTPS URL и один раз раскрыть его секрет подписи |
| `DELETE` | `/webhook-endpoints/{endpoint_id}` | `webhooks:write` | Удалить конечную точку и остановить будущую доставку                        |

URL вебхуков должны использовать HTTPS, не могут включать учётные данные или пользовательский порт и должны разрешаться только в публичные IP-адреса.

## Пагинация [#пагинация]

Пагинированные коллекции принимают `limit` от `1` до `100`; по умолчанию `50`. Используйте возвращённый непрозрачный `next_cursor` только с той же коллекцией и фильтрами.

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Некоторые малые коллекции конфигурации возвращают ту же оболочку с `has_more: false` и не нуждаются в курсоре.

## Идемпотентность [#идемпотентность]

Ключ идемпотентности должен содержать 8–200 символов из букв, цифр, `.`, `_`, `:` и `-`. Результаты хранятся 24 часа и привязаны к владельцу учётных данных.

* Тот же ключ и тот же метод, путь, запрос и тело: возвращает сохранённый ответ с `x-idempotent-replayed: true`.
* Тот же ключ с другим вводом: возвращает `409 conflict`.
* Тот же ключ, пока первый запрос обрабатывается: возвращает `409 conflict` и `Retry-After: 2`.

Сохраняйте ключ перед отправкой мутации и используйте повторно только для повторов этой логической операции.

## Ответы и ошибки [#ответы-и-ошибки]

Успешные ответы оборачивают свой ресурс в `data`. Операции создания обычно возвращают `201`; поставленные в очередь отправки рассылок возвращают `202`; другие успешные операции возвращают `200`. Каждый ответ включает `x-request-id` и использует `Cache-Control: no-store` для данных API.

См. [Области и ошибки](/ru/docs/api/scopes-errors) для полной таблицы кодов ошибок и [Рецепты API](/ru/docs/api/recipes) для копируемых процессов.

---

# Области и ошибки

Source: /ru/docs/api/scopes-errors.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;26 областей&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Стабильные коды&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;ID запросов&#x22;, icon: &#x22;link&#x22; }]" />

Каждая операция публичного API требует одну явную область. Валидные учётные данные без этой области получают `403 insufficient_scope`; они никогда не повышаются молча до более широкого доступа.

## Справочник областей [#справочник-областей]

| Область               | Разрешает                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `account:read`        | Читать аутентифицированный аккаунт, тариф, права и сводку кошелька                                             |
| `sites:read`          | Перечислять и получать сайты                                                                                   |
| `sites:write`         | Создавать, обновлять, публиковать и отменять публикацию сайтов                                                 |
| `agents:read`         | Читать настройки агентов                                                                                       |
| `agents:write`        | Обновлять характер, инструкции, языки, голос, состояние встраивания и разрешённые origin                       |
| `knowledge:read`      | Перечислять источники знаний и FAQ                                                                             |
| `knowledge:write`     | Принимать или удалять текстовые источники и создавать, обновлять или удалять FAQ                               |
| `conversations:read`  | Перечислять диалоги и получать их сообщения                                                                    |
| `leads:read`          | Перечислять собранные заявки                                                                                   |
| `leads:write`         | Создавать, обновлять, квалифицировать и принимать заявки в воронку возможностей                                |
| `pipeline:read`       | Читать стадии, аккаунты, возможности, активности и состояние синхронизации CRM                                 |
| `pipeline:write`      | Настраивать стадии; создавать или обновлять возможности и аккаунты; импортировать или повторять результаты CRM |
| `analytics:read`      | Читать события аналитики сайта                                                                                 |
| `connectors:read`     | Перечислять состояние коннекторов без возврата секретов                                                        |
| `connectors:write`    | Создавать, обновлять, включать, отключать и удалять коннекторы                                                 |
| `domains:read`        | Читать состояние доменов и требуемые DNS-записи                                                                |
| `domains:write`       | Подключать, проверять, обновлять и удалять домены                                                              |
| `broadcasts:read`     | Перечислять рассылки и состояние доставки                                                                      |
| `broadcasts:write`    | Создавать черновики и ставить в очередь отправку рассылки                                                      |
| `notifications:read`  | Перечислять уведомления владельца                                                                              |
| `notifications:write` | Отмечать уведомления прочитанными или непрочитанными                                                           |
| `monetization:read`   | Перечислять продукты монетизации                                                                               |
| `monetization:write`  | Создавать, обновлять, активировать, деактивировать и удалять продукты                                          |
| `usage:read`          | Читать учитываемые события использования                                                                       |
| `webhooks:read`       | Перечислять конечные точки вебхуков и состояние доставки                                                       |
| `webhooks:write`      | Создавать и удалять конечные точки вебхуков                                                                    |

Используйте области чтения для задач отчётности. Добавляйте область записи только когда интеграция выполняет эту мутацию. Например, экспорту заявок обычно нужны `sites:read` и `leads:read`, а не `sites:write` или `agents:write`.

## Сбои областей [#сбои-областей]

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}
```

Создайте замещающий ключ с недостающей областью и обновите серверный секрет. Области существующего ключа API нельзя расширить на месте; это делает изменения привилегий явными и аудируемыми.

## Оболочка ошибок [#оболочка-ошибок]

Все ошибки API используют одну форму верхнего уровня:

```ts
type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};
```

Ветвитесь на `error.code`, а не на английском `message`. Сообщения могут улучшаться без смены версии. Логируйте `error.request_id` и заголовок ответа `x-request-id` с именем операции, статусом и попыткой повтора — но никогда не логируйте заголовок авторизации или секреты запроса.

## Справочник статусов и кодов [#справочник-статусов-и-кодов]

| HTTP  | Стабильный код            | Значение                                                                  | Нормальный ответ                                                      |
| ----- | ------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400` | `invalid_request`         | Валидация не прошла или поле не поддерживается                            | Исправьте поля в `details`; не повторяйте неизменённый ввод           |
| `400` | `invalid_json`            | Тело не является объектом JSON или содержит невалидный JSON               | Сериализуйте один валидный объект JSON                                |
| `401` | `authentication_required` | Заголовок Bearer отсутствует                                              | Прикрепите серверные учётные данные                                   |
| `401` | `invalid_api_key`         | Ключ недействителен, истёк, отозван или его владелец больше не существует | Замените или ротируйте ключ                                           |
| `403` | `subscription_required`   | У владельца нет активного платного тарифа                                 | Восстановите подписку перед повтором                                  |
| `403` | `insufficient_scope`      | Учётным данным не хватает области операции                                | Создайте замещающие учётные данные с минимальными правами             |
| `403` | `account_paused`          | Доступ API приостановлен для аккаунта                                     | Возобновите доступ API или свяжитесь с владельцем аккаунта            |
| `404` | `not_found`               | Конечная точка или принадлежащий ресурс не найдены                        | Проверьте путь и ID, принадлежащий арендатору                         |
| `409` | `conflict`                | Текущее состояние ресурса предотвращает действие                          | Прочитайте текущее состояние перед повтором                           |
| `415` | `invalid_request`         | Тело мутации не `application/json`                                        | Отправьте `Content-Type: application/json`                            |
| `429` | `rate_limit_exceeded`     | Минутная корзина тарифа ключа исчерпана                                   | Дождитесь `Retry-After` и примените джиттер                           |
| `500` | `internal_error`          | Запрос не может быть завершён                                             | Повторите безопасную или идемпотентную операцию и сообщите ID запроса |

Ресурсы вне аккаунта владельца учётных данных могут возвращать `404` вместо раскрытия, существует ли ID другого арендатора.

## Детали валидации [#детали-валидации]

Валидация полей возвращает пути, которые можно показать рядом с вашими собственными элементами формы:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}
```

Тела мутаций должны быть объектами JSON. Массивы, пустые тела, данные формы и JSON, отправленный с текстовым типом контента, отклоняются.

## Решения о повторе [#решения-о-повторе]

* Повторяйте `429` после числа секунд в `Retry-After`.
* Повторяйте `500` только для безопасных чтений или записей, защищённых тем же `Idempotency-Key`.
* Повторяйте идемпотентный `409` в процессе после его заголовка `Retry-After: 2`.
* Не повторяйте `400`, `401`, `403`, `404` или конфликт состояния, пока причина не изменится.

См. [Лимиты частоты](/ru/docs/api/rate-limits) для поведения отката и [Справочник API](/ru/docs/api/reference) для требуемой области каждой операции.

---

# Статус SDK

Source: /ru/docs/api/sdks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;REST доступен&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;OpenAPI&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;Предпросмотр SDK&#x22;, icon: &#x22;bolt&#x22; }]" />

Версионированный REST API — поддерживаемая публичная поверхность интеграции сегодня. Исходники клиентов JavaScript, Python и фреймворков существуют в репозитории продукта, но пакеты пока не опубликованы в npm или PyPI.

## Доступность [#доступность]

| Клиент                       | Статус                                  | Как использовать                                                                                         |
| ---------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| REST поверх HTTPS            | **Доступен**                            | Вызывайте `https://makeagent.fast/api/v1` из любого серверного HTTP-клиента                              |
| Документ OpenAPI             | **Доступен**                            | Скачайте [/api/openapi.json](/api/openapi.json) и изучите его перед генерацией клиента                   |
| `@make-agent-fast/sdk`       | **Предпросмотр исходников — не в npm**  | Не добавляйте этот импорт в продакшен-проект, пока релиз реестра не будет связан здесь                   |
| Пакет Python `makeagentfast` | **Предпросмотр исходников — не в PyPI** | Используйте `requests`, `httpx` или стандартную библиотеку Python, пока релиз PyPI не будет связан здесь |
| Адаптеры React, Vue, Svelte  | **Предпросмотр исходников — не в npm**  | Предпочитайте задокументированный паттерн загрузчика скрипта для фреймворка                              |
| Веб-компонент                | **Предпросмотр исходников — не в npm**  | Предпочитайте стандартный загрузчик `embed.js`                                                           |

<Callout title="Папка с исходниками — не релиз пакета" tone="warning">
  Не запускайте `npm install @make-agent-fast/sdk` или `pip install makeagentfast` только на основе примера импорта. Эта страница будет включать URL реестра, версию, рекомендации по целостности и команду установки, когда публичный пакет будет выпущен.
</Callout>

## JavaScript без SDK [#javascript-без-sdk]

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);
```

Держите ключ API на сервере. Браузерный бандл React, Vue или Svelte должен вызывать ваш собственный бэкенд или устанавливать публичный загрузчик встраивания; он не должен вызывать API управления с секретом.

## Python без SDK [#python-без-sdk]

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])
```

Ловите `urllib.error.HTTPError` в продакшене и разбирайте его тело JSON, используя [стабильную оболочку ошибок](/ru/docs/api/scopes-errors).

## Сгенерированные клиенты [#сгенерированные-клиенты]

Генерация OpenAPI полезна только когда документ содержит операции и схемы, от которых зависит ваше приложение. Закрепите скачанную спецификацию, генерируйте в проверяемую директорию и изучайте каждый diff перед обновлением.

```bash
curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json
```

Не регенерируйте и не развёртывайте клиента автоматически с живого URL. Новое добавочное поле не должно ломать клиента, но поведение генератора и имена сгенерированных методов всё равно могут меняться.

## Что должен включать публичный релиз SDK [#что-должен-включать-публичный-релиз-sdk]

Перед пометкой любого предварительного клиента как доступного у него должны быть:

* Публичная страница реестра и неизменяемая семантическая версия.
* Инструкции по установке, обновлению и поддерживаемым средам выполнения.
* Типизированные модели запросов и ответов, сгенерированные из полного контракта API.
* Структурированные ошибки, сохраняющие HTTP статус и ID запроса.
* Помощники пагинации, трактующие курсоры как непрозрачные.
* Явная поддержка ключей идемпотентности для мутаций.
* Тесты CI против текущего контракта `/api/v1` и опубликованный журнал изменений.

Пока эти условия не выполнены, используйте примеры REST в [Быстром старте API](/ru/docs/api/quickstart) и [Рецептах API](/ru/docs/api/recipes).

---

# Вебхуки

Source: /ru/docs/api/webhooks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;HMAC-SHA256&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Минимум раз&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;8 попыток&#x22;, icon: &#x22;layers&#x22; }]" />

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

## Зарегистрируйте конечную точку [#зарегистрируйте-конечную-точку]

Создайте ключ с `webhooks:write`, затем зарегистрируйте публичный HTTPS приёмник и наименьший набор событий, который вам нужен.

```bash
curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-production-v1" \
  -d '{
    "url": "https://api.example.com/webhooks/make-agent-fast",
    "events": ["lead.created", "conversation.started"]
  }'
```

URL должен использовать HTTPS, не может содержать имя пользователя, пароль, фрагмент или пользовательский порт и должен разрешаться только в публичные IP-адреса. Редиректы не выполняются во время доставки.

Ответ `201` один раз раскрывает секрет подписи `whsec_...`. Сохраните его в менеджере секретов приёмника перед закрытием ответа. Перечисление конечных точек позже возвращает URL, события, статус, последнюю доставку и последнюю ошибку — но не секрет.

## Типы событий [#типы-событий]

| Событие                        | Испускается когда                                                                 |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `site.published`               | Сайт становится опубликованным                                                    |
| `site.unpublished`             | Сайт возвращается в состояние черновика                                           |
| `lead.created`                 | Агент собирает новую заявку                                                       |
| `conversation.started`         | Начинается новая ветка диалога                                                    |
| `conversation.message.created` | Сообщение добавляется в диалог                                                    |
| `knowledge.ready`              | Источник знаний завершает обработку                                               |
| `broadcast.sent`               | Рассылка завершает процесс отправки                                               |
| `domain.activated`             | Устарело — собственные домены не предлагаются; это событие никогда не испускается |

## Формат запроса [#формат-запроса]

Make Agent Fast отправляет `POST` с `Content-Type: application/json`, `User-Agent: MakeAgentFast-Webhooks/1.0` и этими заголовками:

```http
maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256
```

Тело JSON имеет стабильную оболочку. Поля внутри `data` зависят от события и могут получать добавочные поля.

```json
{
  "id": "evt_2c34...",
  "type": "lead.created",
  "created_at": "2026-07-16T10:02:46.000Z",
  "data": {
    "site_id": "SITE_ID",
    "lead_id": "LEAD_ID"
  }
}
```

Используйте `id` тела или `maf-event-id` как ключ дедупликации. Не используйте время доставки или сгенерированный ID базы данных.

## Проверьте подпись в Node.js [#проверьте-подпись-в-nodejs]

Читайте точные сырые байты до разбора JSON. Подписанное значение — `TIMESTAMP + "." + RAW_BODY`.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  const supplied = values.v1;
  if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;

  const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}
```

Отклоняйте неверно сформированные подписи и временные метки старше вашего принятого окна повторного воспроизведения; пять минут — разумное значение по умолчанию. Сравнивайте байты фиксированной длины за постоянное время.

## Проверьте подпись в Python [#проверьте-подпись-в-python]

```python
import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = values.get("t", "")
    supplied = values.get("v1", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, supplied)
```

Разбирайте и обрабатывайте JSON только после успеха проверки подписи.

## Подтверждайте и обрабатывайте [#подтверждайте-и-обрабатывайте]

1. Проверьте подпись и временную метку.
2. Вставьте ID события в таблицу с уникальным ограничением.
3. Если оно уже существует, верните `204` без повторения побочного эффекта.
4. Зафиксируйте событие или поставьте в очередь вашу внутреннюю задачу.
5. Быстро верните ответ `2xx`.

Отправитель Make Agent Fast истекает по времени после 10 секунд. Он считает успешными только `2xx` и не выполняет редиректы.

## Поведение повторов [#поведение-повторов]

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

Возвращайте ответ не-2xx только когда хотите, чтобы Make Agent Fast повторил. Для навсегда неподдерживаемой версии события или удалённого назначения примите и запишите его или удалите конечную точку вместо производства бесконечных временных сбоев.

## Ротируйте секрет подписи [#ротируйте-секрет-подписи]

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

1. Создайте вторую конечную точку, указывающую на временный или версионный путь приёмника.
2. Сохраните её недавно раскрытый секрет.
3. Принимайте и дедуплицируйте события от обеих конечных точек.
4. Проверьте, что новая конечная точка получает валидные доставки.
5. Удалите старую конечную точку через `DELETE /webhook-endpoints/{endpoint_id}`.

Если URL приёмника остаётся тем же, заставьте принимающее приложение принимать оба секрета во время перекрытия и используйте ID событий для предотвращения дублирующих побочных эффектов.

## Решение проблем [#решение-проблем]

| Симптом                  | Проверка                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Нет доставок             | Статус конечной точки, выбранные события, публичный DNS, сертификат HTTPS и произошло ли событие вообще                   |
| Несовпадение подписи     | Доступ к сырому телу, точная конкатенация `timestamp.body`, правильный секрет конечной точки и трансформации тела проксей |
| Повторные доставки       | Код возврата, 10-секундный таймаут, внутренние исключения и уникальность ID событий                                       |
| Ошибка приватного адреса | Записи DNS должны разрешаться только в публичные адреса; localhost и внутренние диапазоны отклоняются                     |
| Сбой редиректа           | Зарегистрируйте финальный HTTPS URL напрямую; редиректы не выполняются                                                    |

Никогда не включайте секрет подписи, ключ bearer или полную полезную нагрузку посетителя в сообщение поддержки. Включайте ID конечной точки, ID события, время сбоя и очищенные логи приёмника.

---

# Внешний вид

Source: /ru/docs/build/appearance.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Тема&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;Чат&#x22;, icon: &#x22;chat&#x22; }, { label: &#x22;Живой звонок&#x22;, icon: &#x22;voice&#x22; }]" />

**Внешний вид** стилизует **чат** и **живой звонок** посетителя вместе — цвета, тему, углы, тень, стекло и шрифты. Он не строит размещённую маркетинговую страницу. Новые агенты запускаются как встраивание на вашем существующем сайте.

Откройте страницу **Внешний вид** сайта. Каждый элемент управления применяется к обеим поверхностям.

## Сохранение сразу уходит в паблик [#сохранение-сразу-уходит-в-паблик]

Выберите **Сохранить внешний вид**. Сохранение записывает строку агента и обновляет встраивание (и любую оставшуюся размещённую страницу), так что посетители видят изменение без ожидания повторной публикации. Подтверждайте в приватном окне на реальном встраивании.

Несохранённый предпросмотр в панели — только предпросмотр. Скрытие/показ значка на Operate и Scale использует то же живое обновление.

## Как на сайте против Светлой и Тёмной [#как-на-сайте-против-светлой-и-тёмной]

**Тема агента** имеет три варианта:

| Вариант          | Эффект                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| **Как на сайте** | Следует светлому или тёмному режиму каждого посетителя (страница сайта, затем ОС). По умолчанию. |
| **Светлая**      | Фиксирует чат и живой звонок на светлой палитре.                                                 |
| **Тёмная**       | Фиксирует чат и живой звонок на тёмной палитре.                                                  |

**Как на сайте** — это `auto`. Фиксированная Светлая или Тёмная закрепляет и чат, и живой звонок для каждого посетителя. Редактируйте светлую и тёмную палитры отдельно; переключатель предпросмотра меняет только то, какую палитру вы редактируете.

Во встраивании загрузчик всё ещё может передать `data-theme="light"` или `data-theme="dark"` как переопределение сайта. См. [Обзор встраивания](/ru/docs/embed/overview).

## Цвета, пресеты и шрифт [#цвета-пресеты-и-шрифт]

* **Пресеты** — Sharp, Soft, Glass, Minimal — задают углы, тень, рамку и стекло вместе.
* **Основной цвет** — пузыри посетителя, акценты звонка и главные действия. &#x2A;*Авто (акцент сайта)** наследует акцент просканированного бренда, использованный для виджета.
* Точно настраивайте вторичный цвет, фон, поверхность панели, углы, тень, рамку, стекло и шрифт.
* **Как на сайте** для шрифта применяется, когда агент встроен на внешний сайт; **По умолчанию виджета** сохраняет шрифт виджета.

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

## Живой разговор в предпросмотре внешнего вида [#живой-разговор-в-предпросмотре-внешнего-вида]

Предпросмотр внешнего вида может показать чат или живой звонок с выбранной светлой или тёмной палитрой. Этот предпросмотр использует ту же оболочку посетителя, что и встраивание. **Поговорите с агентом** в панели (Проверка и тестировщик агента) использует оболочку платформы — см. [Голос и живые звонки](/ru/docs/build/voice).

## Значок брендинга [#значок-брендинга]

Удаление значка доступно на Operate и Scale. Сайты Launch сохраняют реферальный значок Make Agent Fast. Сохранение настройки значка тоже обновляет живое встраивание без повторной публикации.

---

# Создание агента

Source: /ru/docs/build/create-agent.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/build/persona&#x22;, label: &#x22;Характер&#x22;, icon: &#x22;account&#x22; },
{ href: &#x22;/ru/docs/build/knowledge&#x22;, label: &#x22;Знания&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ru/docs/build/voice&#x22;, label: &#x22;Голос&#x22;, icon: &#x22;voice&#x22; },
{ href: &#x22;/ru/docs/build/appearance&#x22;, label: &#x22;Внешний вид&#x22;, icon: &#x22;spark&#x22; }
]"
/>

Первый агент начинается с **URL сайта**. Мы сканируем доступные публичные страницы, готовим черновик агента (внешний вид виджета по этим фактам) и оставляем результат неопубликованным, пока вы его не утвердите. Сборка через чат отключена. Функций генерации сайта или конструктора секций нет.

## Вставьте URL [#вставьте-url]

На главной странице вставьте URL и продолжите. Регистрация и вход сохраняют `next=/onboarding/launch?url=…`, поэтому вставлять его снова не придётся. `/try` позволяет посетителям вставить URL и поговорить с черновиком с водяным знаком (только текст, с ограничением) до его активации при регистрации.

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

Не вставляйте пароли, приватные данные клиентов или токены коннекторов в поле URL.

## Подождите на экране генерации [#подождите-на-экране-генерации]

Пока собирается черновик, экран генерации показывает реальный прогресс чтения, сборки и проверки — не декоративный индикатор:

| Шаг                  | Что он делает                                               |
| -------------------- | ----------------------------------------------------------- |
| **Чтение сайта**     | Загружает публичные страницы по URL                         |
| **Сборка агента**    | Составляет агента и внешний вид виджета из найденных фактов |
| **Проверка ответов** | Прогоняет самопроверку по этим знаниям                      |

Обычное ожидание — несколько секунд; большой сайт может занять до минуты. Если сканирование дало мало материала, черновик всё равно использует найденное. Источники можно добавить после проверки.

Черновик никогда не публикуется автоматически. Новые агенты не получают размещённую маркетинговую страницу.

## Проверка и публикация [#проверка-и-публикация]

Вы попадаете на **Проверка и публикация** (первый пункт в боковом меню сайта):

* **Предпросмотр** виджета посетителя
* **Поговорите с агентом** — спросите то, что спросил бы клиент
* **Самопроверка** — необязательные оцениваемые вопросы по вашим знаниям
* **Утвердить и опубликовать** — включает встраивание на вашем существующем сайте

Разговор с агентом здесь — тест владельца. Он не уходит в паблик и не засчитывается в активацию.

Когда ответы звучат как вы, выберите **Утвердить и опубликовать**. Это включает встраивание (`goLiveEmbedAction`). Скопируйте сниппет из раздела **Встраивание** и добавьте его на свой сайт. Отменить публикацию (отключить встраивание) можно в любой момент.

## Активация [#активация]

После запуска добавьте встраивание или подключите канал. Сайт **активируется** первым диалогом посетителя или первой собранной заявкой. Ходы тестировщика в панели никогда не засчитываются.

## Правки после первого черновика [#правки-после-первого-черновика]

Сборки через чат нет. После проверки обновляйте:

* **Характер**, **Знания**, **Голос** и **Внешний вид** на их собственных страницах.
* Сохранение **внешнего вида** обновляет живое встраивание без повторной публикации.

## Начало без URL сайта [#начало-без-url-сайта]

Если отправить форму на главной пустой, **Try** всё равно откроется. Анонимные посетители могут вставить URL там и поговорить с черновиком; активируйте его при регистрации, чтобы продолжить проверку. Вставленный URL всегда идёт по пути экрана генерации выше.

---

# FAQ и товары

Source: /ru/docs/build/faqs-products.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;FAQ&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Товары&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Знания&#x22;, icon: &#x22;link&#x22; }]" />

## Используйте FAQ для канонических ответов [#используйте-faq-для-канонических-ответов]

Создавайте один FAQ на намерение посетителя. Пишите вопрос языком клиентов и держите ответ полным без опоры на другой FAQ.

## Используйте товары для фактов каталога [#используйте-товары-для-фактов-каталога]

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

## Избегайте дублирования [#избегайте-дублирования]

Не поддерживайте одну цену в заметке, FAQ, разделе страницы и записи товара. Выберите один канонический источник и ссылайтесь на него в других местах.

## Проверяйте клиентское поведение [#проверяйте-клиентское-поведение]

После изменения задайте агенту FAQ в нескольких формулировках и убедитесь, что ссылка и цена товара верны.

---

# Источники знаний

Source: /ru/docs/build/knowledge.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Вставка&#x22;, description: &#x22;Факты и политики от владельца до 200 000 символов.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;URL и ленты&#x22;, description: &#x22;Загрузка публичных страниц или периодического контента сайта.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Файлы&#x22;, description: &#x22;Извлечение выделяемого текста из PDF, TXT, Markdown и CSV.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Медиа&#x22;, description: &#x22;Используйте доступные субтитры YouTube или транскрибируйте поддерживаемое аудио подкастов.&#x22; }
]"
/>

Знания дают агенту исходный материал для поиска. Добавление источника извлекает простой текст, делит его на фрагменты, создаёт эмбеддинги и связывает эти фрагменты с текущим сайтом. При ответе агент извлекает релевантные фрагменты вместо получения всех источников в каждом промпте.

## Выберите правильный тип источника [#выберите-правильный-тип-источника]

| Источник     | Лучше всего для                                      | Важное поведение                                                                        |
| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Вставка**  | Политики, контакты, короткие внутренние заметки      | 5–200 000 символов; без автоматического обновления                                      |
| **URL**      | Публичные страницы, поддерживаемые в другом месте    | Одна страница по умолчанию; опционально сканирование 5, 10 или 20 страниц того же сайта |
| **Загрузка** | PDF, `.txt`, `.md`, `.markdown`, `.csv`              | Максимум 20 МБ; в отсканированных PDF только изображения без выделяемого текста         |
| **YouTube**  | Публичные видео с полезным устным содержимым         | Сначала пробует субтитры, затем доступную транскрибацию; наилучшие усилия               |
| **Подкаст**  | Публичный URL аудио эпизода или поддерживаемая лента | Требует загружаемого аудио и доступного провайдера транскрибации                        |
| **Лента**    | Публичные обновления блога или подкаста RSS/Atom     | Извлекает доступные элементы ленты как текст; наилучшие усилия                          |

Используйте **FAQ и товары** для предсказуемых полей вопрос/ответ или каталога вместо захоронения их в длинном документе. См. [FAQ и товары](/ru/docs/build/faqs-products).

## Добавьте источник [#добавьте-источник]

1. Откройте страницу **Агент** сайта и найдите **Знания**.
2. Выберите **Вставка**, **URL**, **Загрузка**, **YouTube**, **Подкаст** или **Лента**.
3. Введите содержимое или выберите файл.
4. Для обычного URL выберите число страниц для сканирования. Для загружаемых источников опционально выберите автообновление **Ежедневно**, **Еженедельно** или **Никогда**.
5. Выберите **Добавить** и дождитесь результата с числом проиндексированных фрагментов.
6. Задайте вопрос, ответ на который есть только в новом источнике.

Приём знаний расходует кредиты, потому что фрагменты источника эмбеддятся. Он отклоняется, когда у рабочего пространства нет активного доступа или пригодного баланса кредитов.

## Сканируйте публичные страницы безопасно [#сканируйте-публичные-страницы-безопасно]

Краулер принимает публичный HTTP/HTTPS контент и блокирует небезопасные адреса приватных сетей. Начните с одной канонической страницы. Увеличивайте число страниц только когда связанные страницы — часть того же полезного набора информации; большее сканирование может добавить навигацию, юридический шаблон, дублированный текст или устаревшие архивы, ослабляющие поиск.

Выбранное число — максимум, а не обещание. Поведение robots, аутентификация, клиентский рендеринг, редиректы, тип контента, размер ответа и структура ссылок могут уменьшить полученное число. Ответ страницы ограничен 5 МБ и должен содержать достаточно извлекаемого текста.

Для важных фактов за логином вставьте утверждённое резюме или загрузите очищенный экспорт вместо попытки сканировать аутентифицированную страницу.

## Используйте файлы и медиа [#используйте-файлы-и-медиа]

Загруженные PDF и текстоподобные файлы должны содержать извлекаемый текст. OCR для отсканированного PDF только с изображениями не выполняется; конвертируйте его в текст с возможностью поиска перед загрузкой. Держите таблицы простыми, потому что документы со сложной вёрсткой выравниваются в порядок чтения при извлечении.

Приём YouTube предпочитает доступную дорожку субтитров. Если субтитры недоступны, транскрибация зависит от провайдера и сети. Аудио подкаста должно быть публично загружаемым. Результаты ленты зависят от того, сколько текста статьи или эпизода она раскрывает. После любого импорта медиа проверьте заголовок источника и число фрагментов и протестируйте конкретный факт вместо предположения, что вся запись захвачена.

## Планируйте обновление и замену [#планируйте-обновление-и-замену]

Ежедневные и еженедельные расписания доступны для источников URL, YouTube, подкастов и лент. Система повторно загружает сохранённый источник и заменяет его извлекаемые фрагменты при успешном плановом сканировании. Список источников показывает периодичность обновления и время последнего обновления.

Источники вставки и загрузки — снимки. Чтобы исправить или заменить один, удалите его и добавьте обновлённое содержимое. Удаление источника убирает его фрагменты из будущего поиска; оно не редактирует исторические сообщения, уже процитировавшие или пересказавшие старую версию.

Используйте одного понятного владельца для цен, политик и расписаний. Если два активных источника противоречат, поиск может всплыть любое утверждение. Удаляйте заменённые версии вместо добавления «новых» копий рядом.

## Пишите контент, который агент может найти [#пишите-контент-который-агент-может-найти]

* Называйте тему в каждом разделе: «Политика отмены тарифа Pro» находится лучше, чем «Подробнее».
* Размещайте ответ простым языком рядом с соответствующим заголовком.
* Включайте единицы, валюту, часовой пояс, дату вступления в силу и исключения там, где это важно.
* Используйте стабильные канонические URL и описательные имена файлов.
* Отделяйте публичную информацию от внутренних инструкций и приватных записей.
* Держите поведение характера в [Характере и инструкциях](/ru/docs/build/persona), а не внутри фактического исходного материала.

## Тестируйте обоснованные ответы [#тестируйте-обоснованные-ответы]

Создайте небольшой приёмочный набор перед публикацией:

1. Прямой вопрос, ответ на который явно есть в источнике.
2. Перефразировка другими словами.
3. Граничный вопрос, на который источник не отвечает.
4. Недавно изменённый факт.
5. Языковой вариант для каждого настроенного языка агента.

Правильный результат — не всегда уверенный ответ. Когда в источнике нет факта, агент должен следовать инструкциям запасного ответа/эскалации, а не выдумывать. Проверяйте **Диалоги** после запуска на повторяющиеся вопросы без ответа и превращайте проверенные ответы в источник или структурированный FAQ.

## Решение проблем [#решение-проблем]

| Симптом                                       | Проверка                                                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| URL сообщает об отсутствии пригодного текста  | Публичный доступ, поддерживаемый тип контента, серверно отрендеренный текст, цель редиректа и размер страницы |
| PDF сообщает об отсутствии выделяемого текста | Скан ли это; прогоните OCR/экспортируйте в PDF с поиском или текстовый файл                                   |
| Импорт YouTube/подкаста не работает           | Публичный URL, доступность субтитров/аудио, ключ провайдера транскрибации и ограничения загрузки              |
| Правильный факт игнорируется                  | Результат обработки, формулировка, конфликтующие источники, возраст источника и точный тестовый вопрос        |
| Агент раскрывает слишком много                | Немедленно удалите приватный источник и ужесточите границы характера и доступ к аккаунту                      |
| Старый ответ сохраняется                      | Удалите/замените устаревший источник, дождитесь переиндексации и начните новый тестовый диалог                |

Никогда не загружайте учётные данные, приватные ключи, неограниченные экспорты клиентов, медицинские записи или любой контент, который публичный агент не должен раскрывать.

---

# Характер и инструкции

Source: /ru/docs/build/persona.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Правила характера&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Границы&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Языки&#x22;, icon: &#x22;globe&#x22; }]" />

## Отделите идентичность от знаний [#отделите-идентичность-от-знаний]

Характер объясняет, кто агент и как он себя ведёт. Знания поставляют факты. «Говори как ассистент поддержки Acme» помещайте в характер; текущий гарантийный срок — в источник знаний.

## Порядок инструкций [#порядок-инструкций]

Пишите инструкции в этом порядке:

1. Идентичность и роль
2. Основная цель посетителя
3. Тон и длина ответа
4. Обязательные действия и вопросы
5. Запрещённые утверждения и чувствительные темы
6. Условия эскалации и сбора заявок

## Границы [#границы]

Укажите агенту, когда говорить, что он не знает, когда цитировать или уточнять ответ и когда предлагать помощь человека. Никогда не инструктируйте его скрывать неопределённость или выдумывать недостающие данные.

## Тестируйте изменения [#тестируйте-изменения]

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

---

# Голос и живые звонки

Source: /ru/docs/build/voice.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Стандартные голоса&#x22;, icon: &#x22;voice&#x22; },
{ label: &#x22;Голосовые сообщения&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Клонирование&#x22;, icon: &#x22;spark&#x22; },
{ label: &#x22;Живые звонки&#x22;, icon: &#x22;bolt&#x22; }
]"
/>

## Поймите три режима взаимодействия [#поймите-три-режима-взаимодействия]

| Режим                               | Опыт посетителя                                                     | Права и использование                                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Текстовый чат**                   | Печатает сообщение и получает текст                                 | Всегда включён; расходует обычные кредиты ИИ                                                                            |
| **Голосовые сообщения**             | Записывает сообщение, ждёт транскрибации/агента/TTS, получает ответ | Включены во все тарифы; транскрибация, модель и работа речи расходуют кредиты                                           |
| **Живой звонок в реальном времени** | Ведёт разговор с низкой задержкой                                   | Operate: 30 мин/мес; Scale: 90 мин/мес; Launch: недоступно; также заранее списывает кредиты за настроенный лимит звонка |

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

## Настройте поведение взаимодействия [#настройте-поведение-взаимодействия]

1. Откройте страницу **Агент** сайта и найдите **Голос**.
2. Оставьте **Текстовый чат** включённым и выберите **Голосовые сообщения** и/или **Живой голос в реальном времени**.
3. Если у агента несколько языков, опционально включите живое зеркалирование языка.
4. Установите автоматический лимит на звонок.
5. Выберите стандартный или доступный клонированный голос.
6. Сохраните и протестируйте каждый включённый режим отдельно.

Лимит звонка принимает от 30 секунд до 20 минут с шагом 30 секунд; по умолчанию 3 минуты. Он завершает отдельный звонок и защищает месячный лимит, но не увеличивает оставшиеся живые минуты тарифа.

## Выберите языки и голос [#выберите-языки-и-голос]

Агенты могут быть настроены на английский, корейский, узбекский и русский. Первый язык — основной. Одноязычный агент продолжает отвечать на этом языке. Мультиязычный текстовый агент зеркалит посетителя, когда посетитель использует один из настроенных языков.

Для живых звонков зеркалирование языка — явная опция, показанная только при двух и более языках. Когда оно выключено, живые звонки используют основной язык. Узбекский голос сейчас работает наилучшими усилиями, потому что покрытие речи провайдеров менее полное; проверьте его с вашим точным провайдером и аудиторией перед запуском.

Стандартные голоса включают варианты с приоритетом английского, мультиязычные и родные корейские. Языковая метка описывает подобранную подачу, а не жёсткую гарантию. Прослушивайте выбранный голос, когда доступен элемент предпросмотра в панели, и всегда тестируйте имена, аббревиатуры, валюты, номера телефонов и специализированную терминологию в реальном потоке посетителей.

## Ключи провайдеров и запасной вариант [#ключи-провайдеров-и-запасной-вариант]

Голосу нужно больше, чем ключ модели:

* Речь-в-текст использует настроенный провайдер транскрибации, например Deepgram или OpenAI.
* Голосовым сообщениям и аудио-ответам коннекторов нужен провайдер синтеза речи, например ElevenLabs или OpenAI.
* Звонкам в реальном времени нужны настроенный провайдер реального времени и лимит тарифа.
* Клонирование голоса требует доступности клонирования ElevenLabs плюс права Operate или Scale.

Голос под управлением платформы использует настроенных провайдеров платформы; личный ключ провайдера не требуется для включённого клонирования. Владельцы Scale могут опционально настроить ключи в **Аккаунт → Ключи AI-провайдеров** и следовать [Ключам провайдеров](/ru/docs/account/provider-keys). Успешный текстовый чат доказывает только путь модели; он не доказывает транскрибацию, синтез речи, загрузку медиа или выпуск сессии реального времени.

## Клонированный голос и запасной вариант [#клонированный-голос-и-запасной-вариант]

Автоматическая речь использует Speko для выбора провайдера для английского, корейского, узбекского и русского. Точный стандартный голос может меняться с выбранным провайдером. Явные выборы провайдера остаются доступными. Транскрибация записанных голосовых сообщений тоже по умолчанию использует Speko; родной вход живого звонка остаётся у провайдера живого разговора.

Выбранный сохранённый клон использует ElevenLabs с учётными данными платформы, которым принадлежит клон. Когда маршрутизация клонов платформы включена, это идёт через Speko с ElevenLabs v3; во время настройки прямой маршрут ElevenLabs остаётся доступным. Личный ключ ElevenLabs для включённого клонирования не нужен. Если клонированная речь не работает, отдельный запрос стандартного голоса идёт через Speko. Сбой Speko может переключиться на доступного прямого провайдера. Неудачные попытки освобождают резерв кредитов перед следующей попыткой; сохранённый клон остаётся выбранным для следующего ответа. Если вся речь не работает, текст остаётся доступным.

Живые звонки передают родное аудио напрямую из OpenAI Realtime или Gemini Live. Входная речь транскрибируется независимо для отображения в чате; ни транскрипт входа, ни завершённый текстовый ответ не требуются перед воспроизведением аудио. Используется встроенный голос провайдера реального времени, даже когда для голосовых сообщений выбран клон или Speko. Клонированные голоса остаются доступными для голосовых сообщений. Поиск знаний, языковые правила, прерывание, лимиты живых минут и предварительные списания за звонок по-прежнему действуют. Живые ответы не делают дополнительный запрос TTS.

## Тестируйте голосовые сообщения [#тестируйте-голосовые-сообщения]

Используйте реальное встраивание, а не только предпросмотр владельца. (Оставшиеся размещённые демо-страницы тоже работают, если у вас есть одна.) Выдайте доступ к микрофону, запишите короткий вопрос и подтвердите смысл транскрипта плюс устный/текстовый ответ. Затем проверьте:

* тихую и шумную обстановку;
* мобильные Safari и Chrome, где актуально;
* длинный вопрос рядом с публичным лимитом аудио 25 МБ;
* отказ в разрешении микрофона;
* неподдерживаемое или низкокачественное аудио;
* каждый настроенный язык.

Для встроенных сайтов родительская CSP и Permissions Policy должны разрешать использование микрофона. См. [Безопасность и CSP](/ru/docs/embed/security).

## Живой разговор на платформе против опубликованного сайта [#живой-разговор-на-платформе-против-опубликованного-сайта]

Живой разговор использует те же элементы управления звонком на двух оболочках:

| Поверхность                           | Где                                                                         | Вид                              | Засчитывается как активация?                |
| ------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------- |
| **Тестировщик платформы**             | **Поговорите с агентом** на Проверке и тестировщик на **Агенте**            | Оболочка панели платформы        | Нет — тесты владельца никогда не активируют |
| **Опубликованный сайт и встраивание** | Виджет оставшейся размещённой демо-страницы (если есть) и iframe `embed.js` | Внешний вид арендатора / виджета | Да — звонок посетителя это реальный диалог  |

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

**Как на сайте** во внешнем виде следует светлому или тёмному режиму посетителя на странице сайта и встраивании. Фиксированная Светлая или Тёмная закрепляет и чат, и живой звонок. См. [Внешний вид](/ru/docs/build/appearance).

## Тестируйте живые звонки [#тестируйте-живые-звонки]

Подтвердите, что у тарифа есть неиспользованные живые минуты, сайт доступен и ключ провайдера реального времени валиден. Начните с короткого звонка, прервите агента, переключайте языки только когда включено зеркалирование и позвольте настроенному лимиту звонка завершить одну тестовую сессию. Повторите один звонок на реальном встраивании, а не только в тестировщике панели.

Живые минуты — отдельное месячное право от обычных кредитов. Выдача живого токена списывает кредиты за максимальную серверно-авторизованную длительность и резервирует эту длительность против месячного лимита. Поскольку медиа течёт напрямую между браузером и провайдером, более короткий клиентский звонок не может быть проверен, и неиспользованное время не возвращается частично после выдачи токена. Серверные сбои выпуска токена освобождаются; брошенные сессии списываются по авторизованному лимиту. Завершайте тесты чисто и используйте настроенный лимит звонка при прогнозировании. См. [Кредиты и использование](/ru/docs/operate/usage).

## Клонируйте голос ответственно [#клонируйте-голос-ответственно]

Клонирование голоса недоступно на Launch. Operate включает один клон; Scale разрешает несколько при честном использовании. Повторное клонирование сайта, у которого уже есть клон, заменяет клон этого сайта вместо расходования другого слота.

Используйте только свой голос или голос, на который у вас есть явное документированное разрешение. Форма клонирования требует согласия и может потребовать ввести контрольную фразу, привязанную к сайту. Успешный клон создаёт проверяемую запись согласия, когда включён усиленный контроль согласия.

Загрузите минимум один и максимум 10 аудиообразцов. Каждый файл может быть не более 10 МБ, с общим максимумом 50 МБ. Используйте чистые сухие записи с одним диктором, постоянным расстоянием, минимальным фоновым шумом и репрезентативным произношением. Не смешивайте разных дикторов и сильно обработанную музыку.

Клонирование резервирует, а затем рассчитывает кредиты. Неудачный вызов провайдера возвращает резерв; успешный клон становится выбранным голосом агента.

## Раскрытие и безопасность [#раскрытие-и-безопасность]

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

## Решение проблем [#решение-проблем]

| Симптом                                | Проверка                                                                                                                   |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Текст работает, но элементы голоса нет | Ключи провайдеров транскрибации/TTS/реального времени, переключатель функции, тариф, баланс кредитов и разрешение браузера |
| Запись не может начаться               | HTTPS, разрешение микрофона, устройство ввода, Permissions Policy встраивания и поддержка браузера                         |
| Транскрипт неточен                     | Качество аудио, выбранный набор языков, акцент/терминология и покрытие провайдера транскрибации                            |
| Устный ответ звучит неправильно        | Выбранный голос, исходный текст, пунктуация, языковая метка и доступность провайдера                                       |
| Живой звонок сразу завершается         | Оставшиеся минуты, лимит на звонок, ключ провайдера, сеть и состояние параллельных сессий                                  |
| Клон отклонён                          | Слот тарифа, фраза согласия, 1–10 поддерживаемых аудиофайлов, лимиты на файл/суммарно и ключ ElevenLabs                    |

Трактуйте голос как отдельную поверхность запуска: приёмочные тесты текста необходимы, но недостаточны.

---

# Discord

Source: /ru/docs/connectors/discord.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; }
]"
/>

## Создайте приложение Discord [#создайте-приложение-discord]

Следуйте официальному [быстрому старту приложений](https://docs.discord.com/developers/quick-start/getting-started) Discord и [обзору взаимодействий](https://docs.discord.com/developers/interactions/overview). Создайте приложение в Discord Developer Portal и соберите:

| Поле Make Agent Fast | Расположение в Discord | Назначение                                                                       |
| -------------------- | ---------------------- | -------------------------------------------------------------------------------- |
| **Application ID**   | General Information    | Идентифицирует приложение и команду                                              |
| **Public Key**       | General Information    | Проверяет подписанные Ed25519 взаимодействия; ровно 64 шестнадцатеричных символа |
| **Токен бота**       | Страница Bot           | Проверяет приложение и регистрирует `/ask`; держите в секрете                    |

Сброс токена бота немедленно аннулирует предыдущий. Public Key не секретен, но должен принадлежать тому же приложению, что и токен бота.

## Подключите и зарегистрируйте `/ask` [#подключите-и-зарегистрируйте-ask]

Откройте страницу **Коннекторы** сайта, выберите **Discord**, введите три значения и нажмите **Подключить**.

Make Agent Fast проверяет токен бота против конечной точки приложения Discord и отклоняет Public Key, не совпадающий с приложением. Он нормализует опечатанный Application ID к реальному ID аутентифицированного приложения, затем создаёт или обновляет глобальную команду `/ask question`, не удаляя другие команды приложения.

После сохранения скопируйте показанный **Interactions Endpoint URL** в **General Information → Interactions Endpoint URL** в Discord и сохраните. Discord отправляет подписанный `PING`; Make Agent Fast проверяет подпись и возвращает требуемый `PONG`.

## Установите и протестируйте [#установите-и-протестируйте]

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

Запустите `/ask`, заполните обязательную опцию `question` и отправьте. Make Agent Fast подтверждает взаимодействие до короткого дедлайна Discord, запускает агента, затем редактирует отложенный исходный ответ. История диалога привязана к пользователю Discord, поэтому более поздние запросы `/ask` могут сохранять контекст.

Текущий коннектор только текстовый. Он не читает голосовые каналы, вложения, обычные сообщения каналов или личные сообщения; только зарегистрированное взаимодействие `/ask` входит в агента.

## Ротация или отключение [#ротация-или-отключение]

Если токен бота раскрыт, сбросьте его в Discord, обновите коннектор и проверьте `/ask` снова. Если меняется само приложение, обновите все три значения и Interactions Endpoint URL для этого приложения.

Отключение или удаление коннектора не удаляет приложение Discord или глобальную команду. Удалите приложение с серверов и удалите устаревшие учётные данные провайдера отдельно при выводе из эксплуатации.

## Решение проблем [#решение-проблем]

| Симптом                                             | Решение                                                                                                                       |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Коннектор отклоняет поля                            | Используйте токен бота и 64-символьный Public Key из одного приложения                                                        |
| Discord отклоняет конечную точку                    | Подтвердите публичный HTTPS, вставьте сгенерированную конечную точку и пересохраните учётные данные перед повтором            |
| `/ask` отсутствует                                  | Подтвердите установку/авторизацию команды, дождитесь глобального распространения и переподключитесь для повторной регистрации |
| Взаимодействие сообщает, что приложение не ответило | Проверьте, что коннектор включён, и изучите ошибки Make Agent Fast/Discord; проверка подписи конечной точки должна пройти     |
| Другие сообщения чата игнорируются                  | Ожидаемо; интеграция обрабатывает только `/ask`                                                                               |
| Ответ обрезан                                       | Ответы сообщений Discord ограничены 2 000 символами                                                                           |

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

---

# Instagram

Source: /ru/docs/connectors/instagram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; }
]"
/>

## Что делает этот коннектор [#что-делает-этот-коннектор]

Клиенты отправляют **личное сообщение** вашему профессиональному аккаунту Instagram. Make Agent Fast отвечает тем же обоснованным агентом, что и ваше встраивание на сайте. Это официальный [Instagram Messaging API](https://developers.facebook.com/docs/messenger-platform/instagram) на профессиональном аккаунте, привязанном к Facebook-странице.

Вне объёма: ответы комментариев в ЛС, ответы на сторис, комментарии ленты, скрейпинг и неофициальный вход Instagram. Это не ЛС в этом коннекторе.

То же приложение Meta может также питать [Messenger](/ru/docs/connectors/messenger) и [WhatsApp](/ru/docs/connectors/whatsapp). Instagram остаётся **отдельной строкой канала**, чтобы оплата, ветки входящих и привязка вебхуков оставались различимыми.

## Подготовьте приложение Meta и аккаунт Instagram [#подготовьте-приложение-meta-и-аккаунт-instagram]

Следуйте официальному [гайду по началу работы с Instagram Messaging](https://developers.facebook.com/docs/messenger-platform/instagram/get-started) Meta. Вам нужно:

1. **Профессиональный** аккаунт Instagram (Business или Creator).
2. Этот аккаунт, **привязанный** к Facebook-странице, которую вы администрируете.
3. Приложение Meta с продуктом Instagram / Messenger и включёнными сообщениями Instagram.
4. **Токен доступа Страницы** для этой Страницы и **32-символьный шестнадцатеричный секрет приложения**.

Соберите:

| Поле Make Agent Fast       | Значение провайдера                                    | Назначение                                                    |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
| **Токен доступа Страницы** | Токен, выданный для привязанной Facebook-страницы      | Читает привязанный аккаунт Instagram и отправляет ответы в ЛС |
| **Секрет приложения**      | 32-символьный шестнадцатеричный секрет приложения Meta | Проверяет подписанные входящие запросы вебхука                |

Не вставляйте токен доступа пользователя или токен для другой Страницы. Проверка Graph отказывает, если у Страницы нет привязанного профессионального аккаунта Instagram.

На Make Agent Fast нет платформенного OAuth входа Instagram. Вы приносите учётные данные из **вашего** приложения Meta.

## Сохраните и проверьте учётные данные [#сохраните-и-проверьте-учётные-данные]

Откройте страницу **Коннекторы** сайта, выберите **Instagram**, введите токен доступа Страницы и секрет приложения и нажмите **Подключить**.

Make Agent Fast вызывает Graph с `appsecret_proof`, требует `instagram_business_account` и привязывает входящие события к этому id аккаунта Instagram. Затем карточка коннектора показывает свой **URL вебхука** и **Токен проверки**.

Подключение **нового** канала требует Operate или Scale.

## Настройте вебхук Instagram [#настройте-вебхук-instagram]

В том же приложении Meta:

1. Откройте настройки вебхука Instagram (или Messenger).
2. Вставьте **URL вебхука** и **Токен проверки** коннектора.
3. Завершите вызов проверки.
4. Подпишите поле Instagram `messages`.
5. Убедитесь, что Страница и профессиональный аккаунт Instagram связаны с приложением.
6. Убедитесь, что режим приложения разрешает вашего тестового пользователя.

Токен проверки используется только для начального вызова. События во время работы должны нести `X-Hub-Signature-256`, совпадающий с секретом приложения. Make Agent Fast также отклоняет события, адресованные другому аккаунту Instagram, даже если они пришли от того же приложения Meta, и игнорирует полезные нагрузки Messenger `object: "page"` на этом URL.

## Протестируйте возможности [#протестируйте-возможности]

Отправьте обычное ЛС с разрешённого тестового аккаунта не-администратора и подтвердите ответ плюс ветку в **Диалогах**. Затем протестируйте аудиозаметку, если входящий голос важен.

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

## Готовность к продакшену [#готовность-к-продакшену]

Завершите разрешения Meta, **App Review** (`instagram_manage_messages` и связанные разрешения Страницы), проверку бизнеса, URL конфиденциальности и шаги публикации. Успех в режиме разработки с аккаунтом роли приложения не доказывает, что публика может писать интеграции в ЛС.

Задокументируйте владеющее приложение Meta, ID Страницы и ID аккаунта Instagram для операторов. Токен Страницы может перестать работать при изменении владельца, разрешений, связи с бизнесом или политики провайдера.

## Ротация или отключение [#ротация-или-отключение]

Сгенерируйте замещающий токен Страницы, обновите коннектор, протестируйте с разрешённого пользователя, затем аннулируйте старый токен. Обновляйте Make Agent Fast немедленно после ротации секрета приложения.

Отключение или удаление коннектора не отписывает Instagram в Meta. Удалите подписку и неиспользуемые учётные данные провайдера при окончательном выводе интеграции из эксплуатации.

## Решение проблем [#решение-проблем]

| Симптом                                                    | Решение                                                                                                           |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Токен отклонён                                             | Убедитесь, что это токен Страницы для нужной Страницы и секрет приложения принадлежит тому же приложению          |
| Страница валидна, но «нет привязанного аккаунта Instagram» | Привяжите профессиональный аккаунт Instagram к Странице в Meta Business Suite                                     |
| Проверка вебхука не работает                               | Скопируйте текущий URL и токен проверки точно; используйте публичный HTTPS                                        |
| Проверка работает, но сообщения не приходят                | Подпишите поле Instagram `messages`, затем проверьте режим приложения, роль пользователя и логи доставки Meta     |
| Запросы неавторизованы                                     | Исправьте секрет приложения; подписанные POST-запросы не используют токен проверки                                |
| Входящее сообщение появляется, но ответа нет               | Проверьте валидность токена Страницы, `instagram_manage_messages`, ошибку отправки провайдера и статус коннектора |
| Голос получает текстовый ответ                             | Ожидаемо; исходящий голос Instagram сейчас не поддерживается                                                      |
| Публичные клиенты не могут писать в ЛС                     | Завершите Meta App Review; режим разработки доставляет только тестировщикам с ролью приложения                    |

Учётные данные провайдера допустимы только в аутентифицированной форме коннектора или доверенном серверном вызове API.

---

# KakaoTalk

Source: /ru/docs/connectors/kakao.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

## Чек-лист настройки [#чек-лист-настройки]

Карточка KakaoTalk в Make Agent Fast показывает этот список с уже заполненными вашими значениями, поэтому большинство владельцев проходят его там. Каждый шаг происходит в консоли Kakao, кроме двух полей, отмеченных ниже.

1. **Создайте бота** в Kakao i Open Builder. Один бот содержит каждый блок сценария, которым отвечает канал; пропустите этот шаг, если у канала уже есть бот, которого вы можете редактировать.
2. **Добавьте скилл** и установите его URL в **URL скилла** коннектора, затем добавьте пользовательский заголовок запроса `X-Kakao-Bot-Secret`, несущий ваш **Секрет бота**. Kakao не подписывает запросы скилла, поэтому этот заголовок — единственное доказательство, что вызов пришёл от вашего бота.
3. **Направьте резервный блок на скилл**, чтобы каждый вопрос, который ваши сценарии не обрабатывают, достигал агента. Подключите именованный блок сценария к тому же скиллу, когда он тоже должен отвечаться агентом.
4. **Включите опцию обратного вызова** для этого блока. Kakao отбрасывает ответ скилла, занимающий больше пяти секунд; с включённым обратным вызовом Make Agent Fast сразу возвращает пузырь ожидания и отправляет готовый ответ на `userRequest.callbackUrl` в течение минуты, в которую мы считаем этот одноразовый URL живым.
5. **Подключите KakaoTalk-канал** к боту, затем вставьте тот же ID канала в поле **Channel ID** коннектора в Make Agent Fast.
6. **Разверните бота.** Изменения Open Builder достигают посетителей только после развёртывания, и каждое последующее изменение скилла или блока требует ещё одного.

Остальная часть этой страницы — развёрнутая форма тех же шести шагов.

## Подготовьте ресурсы Kakao [#подготовьте-ресурсы-kakao]

Создайте или выберите приложение Kakao Developers, KakaoTalk-канал и бота Kakao i Open Builder, которые будут владеть интеграцией. Изучите официальную [документацию Open Builder](https://i.kakao.com/docs/key-concepts-block#skill) Kakao о скиллах и блоках.

Соберите или создайте эти значения:

| Поле Make Agent Fast | Источник                                         | Назначение                                                     |
| -------------------- | ------------------------------------------------ | -------------------------------------------------------------- |
| **Channel ID**       | Публичный/поисковый ID KakaoTalk-канала          | Связывает коннектор с нужным каналом                           |
| **REST API ключ**    | Ключи приложения Kakao Developers                | Проверяет приложение Kakao                                     |
| **Секрет бота**      | Длинный случайный секрет, который вы генерируете | Аутентифицирует входящие запросы скилла в `X-Kakao-Bot-Secret` |

Секрет бота обязателен на развёрнутых окружениях Make Agent Fast, потому что вызовы скилла Kakao не предоставляют платформенную подпись. Сгенерируйте уникальное значение с высокой энтропией и не используйте REST API ключ как секрет.

## Сохраните коннектор [#сохраните-коннектор]

Откройте страницу **Коннекторы** сайта, выберите **KakaoTalk-канал**, введите все три значения и нажмите **Подключить**. Make Agent Fast проверяет REST API ключ, где позволяют разрешения Kakao, и показывает уникальный **URL вебхука** коннектора после сохранения.

Make Agent Fast не может создать скилл Open Builder или привязать его к блоку за вас; оставшаяся работа — в консоли Kakao.

## Настройте скилл Open Builder [#настройте-скилл-open-builder]

1. В Kakao i Open Builder создайте скилл для нужного бота.
2. Установите URL скилла в скопированный **URL вебхука** коннектора.
3. Добавьте пользовательский заголовок запроса `X-Kakao-Bot-Secret`, значение которого точно совпадает с **Секретом бота**.
4. Подключите скилл к резервному блоку или блоку сценария, который должен вызывать агента.
5. Включите опцию обратного вызова этого блока, чтобы медленные ответы переживали пятисекундный дедлайн скилла Kakao.
6. Сохраните и разверните/опубликуйте конфигурацию бота по процессу Kakao.

Заголовок нечувствителен к регистру по правилам HTTP, но значение секрета точное. Любой, кто знает URL вебхука, но не этот секрет, должен получить неавторизованный ответ.

## Протестируйте возможности [#протестируйте-возможности]

Сначала используйте тестовый инструмент Open Builder, затем подключённый KakaoTalk-канал. Отправьте реалистичный корейский или поддерживаемый языковой текстовый вопрос и подтвердите встроенный ответ, **Последнее сообщение** и ветку в **Диалогах**.

Карточка коннектора копирует тело запроса ниже; то же тело работает с `curl` против URL скилла. Оно не несёт `callbackUrl`, поэтому ответ возвращается встроенным — более простая вещь для первой проверки.

```json
{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}
```

Здоровый скилл отвечает в пределах пятисекундного дедлайна одним выводом `simpleText`:

```json
{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}
```

Когда опция обратного вызова блока включена, Open Builder добавляет `userRequest.callbackUrl` в запрос. Make Agent Fast тогда сначала отвечает пузырём ожидания и отправляет POST готового ответа на этот одноразовый URL:

```json
{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}
```

Текущий контракт скилла только текстовый. Ответ агента — один Kakao `skillResponse` версии `2.0` с выводом `simpleText`, ограниченный ниже текстового лимита Kakao, возвращаемый встроенным или на URL обратного вызова. Голос, файлы, изображения и отдельное исходящее аудио не поддерживаются.

## Ротация или отключение [#ротация-или-отключение]

Чтобы ротировать Секрет бота, обновите коннектор и пользовательский заголовок Open Builder как одно скоординированное изменение, затем немедленно протестируйте. Несовпадение останавливает каждый входящий запрос. Ротируйте REST API ключ в Kakao Developers и Make Agent Fast перед отзывом старого ключа.

Отключение или удаление коннектора не удаляет скилл или блок Open Builder. Удалите или отсоедините эти объекты на стороне провайдера при окончательном выводе интеграции из эксплуатации.

## Решение проблем [#решение-проблем]

| Симптом                                                      | Решение                                                                                    |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Коннектор требует Секрет бота                                | Сгенерируйте его; развёрнутые окружения отказывают неаутентифицированному вебхуку Kakao    |
| REST API ключ отклонён                                       | Используйте REST API ключ нужного приложения Kakao и подтвердите его разрешения канала     |
| Open Builder получает неавторизовано                         | Добавьте/обновите `X-Kakao-Bot-Secret`, чтобы он точно совпадал со значением коннектора    |
| Тестовый инструмент показывает резервный ответ вместо ответа | Убедитесь, что блок вызывает сохранённый URL скилла, и изучите логи запросов/ответов Kakao |
| Запросы истекают по времени                                  | Включите опцию обратного вызова блока; без неё Kakao даёт скиллу пять секунд               |
| Голос или изображения игнорируются                           | Ожидаемо; текущий коннектор принимает только текст                                         |

Не раскрывайте REST API ключ или Секрет бота в клиентском коде или публичной документации.

---

# Messenger

Source: /ru/docs/connectors/messenger.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; }
]"
/>

## Подготовьте приложение Meta и Страницу [#подготовьте-приложение-meta-и-страницу]

Следуйте официальному [гайду по началу работы с Messenger Platform](https://developers.facebook.com/docs/messenger-platform/get-started) Meta. Добавьте Messenger в приложение Meta, подключите Facebook-страницу, которая должна получать сообщения, и убедитесь, что ваш аккаунт может администрировать оба ресурса.

Соберите значения из одного приложения и Страницы:

| Поле Make Agent Fast       | Значение провайдера                                    | Назначение                                       |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------ |
| **Токен доступа Страницы** | Токен, выданный для выбранной Страницы                 | Читает идентичность Страницы и отправляет ответы |
| **Секрет приложения**      | 32-символьный шестнадцатеричный секрет приложения Meta | Проверяет подписанные входящие запросы вебхука   |

Не используйте токен доступа пользователя или токен, принадлежащий другой Странице. Состояние разработки/проверки приложения Meta определяет, кто может использовать интеграцию.

## Сохраните и проверьте учётные данные [#сохраните-и-проверьте-учётные-данные]

Откройте страницу **Коннекторы** сайта, выберите **Messenger**, введите токен доступа Страницы и секрет приложения и нажмите **Подключить**.

Make Agent Fast вызывает Graph API с `appsecret_proof`, разрешает ID/имя Страницы и привязывает входящие события к этой точной Странице. Затем карточка коннектора показывает свой **URL вебхука** и **Токен проверки**.

## Настройте вебхук Страницы [#настройте-вебхук-страницы]

В том же приложении Meta:

1. Откройте настройки вебхука Messenger.
2. Вставьте **URL вебхука** и **Токен проверки** коннектора.
3. Завершите вызов проверки.
4. Выберите подписку на события сообщений, требуемую процессом Messenger.
5. Подпишите нужную Facebook-страницу на приложение.
6. Убедитесь, что подписка Страницы и режим приложения разрешают вашего тестового пользователя.

Токен проверки используется только для начального вызова. События во время работы должны нести подпись, совпадающую с секретом приложения. Make Agent Fast также отклоняет события, адресованные другой Странице, даже если они пришли от того же приложения Meta.

## Протестируйте возможности [#протестируйте-возможности]

Отправьте обычное сообщение на Страницу с разрешённого тестового аккаунта не-администратора и подтвердите ответ плюс ветку в **Диалогах**. Затем протестируйте аудиовложение, если входящий голос важен для вашего процесса.

Текст и поддерживаемое входящее аудио обрабатываются. Ответы в текущем коннекторе Messenger только текстовые, даже когда исходное сообщение было голосовым. Квитанции доставки/прочтения, эхо собственных сообщений Страницы, изображения и другие неподдерживаемые вложения игнорируются.

## Готовность к продакшену [#готовность-к-продакшену]

Завершите разрешения, проверку приложения, проверку бизнеса, URL конфиденциальности и шаги публикации Страницы, которые Meta требует для вашей аудитории. Успех в режиме разработки с аккаунтом роли приложения не доказывает, что публика может писать интеграции Страницы.

Задокументируйте владеющее приложение Meta и ID Страницы для операторов. Токен Страницы может перестать работать при изменении владельца, разрешений, связи с бизнесом или политики провайдера.

## Ротация или отключение [#ротация-или-отключение]

Сгенерируйте замещающий токен Страницы, обновите коннектор, протестируйте с разрешённого пользователя, затем аннулируйте старый токен. Обновляйте Make Agent Fast немедленно после ротации секрета приложения.

Отключение или удаление коннектора не отписывает Страницу в Meta. Удалите подписку Страницы и неиспользуемые учётные данные провайдера при окончательном выводе интеграции из эксплуатации.

## Решение проблем [#решение-проблем]

| Симптом                                      | Решение                                                                                                          |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Токен отклонён                               | Убедитесь, что это токен Страницы для нужной Страницы и секрет приложения принадлежит тому же приложению         |
| Проверка вебхука не работает                 | Скопируйте текущий URL и токен проверки точно; используйте публичный HTTPS                                       |
| Проверка работает, но сообщения не приходят  | Подпишите Страницу и событие сообщений, затем проверьте режим приложения, роль пользователя и логи доставки Meta |
| Запросы неавторизованы                       | Исправьте секрет приложения; подписанные POST-запросы не используют токен проверки                               |
| Входящее сообщение появляется, но ответа нет | Проверьте валидность токена Страницы, разрешения сообщений, ошибку отправки провайдера и статус коннектора       |
| Голос получает текстовый ответ               | Ожидаемо; исходящий голос Messenger сейчас не поддерживается                                                     |

Учётные данные провайдера допустимы только в аутентифицированной форме коннектора или доверенном серверном вызове API.

---

# Обзор коннекторов

Source: /ru/docs/connectors/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/telegram&#x22;, label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; },
{ href: &#x22;/ru/docs/connectors/whatsapp&#x22;, label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; },
{ href: &#x22;/ru/docs/connectors/messenger&#x22;, label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; },
{ href: &#x22;/ru/docs/connectors/instagram&#x22;, label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; },
{ href: &#x22;/ru/docs/connectors/discord&#x22;, label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; },
{ href: &#x22;/ru/docs/connectors/kakao&#x22;, label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

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

Подключение **нового** канала требует Operate или Scale. Существующие подключения продолжают работать на Launch.

## Матрица возможностей [#матрица-возможностей]

| Канал     | Входящий текст | Входящий голос | Исходящий текст         | Исходящий голос | Настройка провайдера после сохранения                                      |
| --------- | -------------- | -------------- | ----------------------- | --------------- | -------------------------------------------------------------------------- |
| Telegram  | Да             | Да             | Да                      | Опционально     | Вебхук регистрируется автоматически                                        |
| WhatsApp  | Да             | Да             | Да                      | Опционально     | Добавьте вебхук Meta и подписку `messages`                                 |
| Messenger | Да             | Да             | Да                      | Нет             | Добавьте вебхук Meta и подпишите Страницу                                  |
| Instagram | Да             | Да             | Да                      | Нет             | Добавьте вебхук Meta Instagram и подпишите `messages`                      |
| Discord   | Вопрос `/ask`  | Нет            | Ответ `/ask`            | Нет             | Вставьте конечную точку взаимодействий; регистрация команды автоматическая |
| KakaoTalk | Да             | Нет            | Встроенный ответ скилла | Нет             | Добавьте URL скилла, заголовок и блок в Open Builder                       |

«Входящий голос» означает, что поддерживаемое голосовое/аудио сообщение загружается и транскрибируется. «Исходящий голос» требует работающего провайдера речи и опции коннектора **Отвечать голосом**. Неподдерживаемые вложения вроде изображений и локаций игнорируются, а не интерпретируются как инструкции агенту.

## Перед подключением [#перед-подключением]

1. Протестируйте предполагаемого агента сайта в панели. Публикация рекомендуется, чтобы его публичные ссылки и страницы работали; черновик коннектора всё равно может отвечать.
2. Настройте рабочий ключ модели в **Настройки → Ключи AI-провайдеров**. Настройте ключи речи перед тестированием голоса. См. [Ключи провайдеров](/ru/docs/account/provider-keys).
3. Создайте выделенное приложение, бота, номер или канал у внешнего провайдера. Не используйте повторно учётные данные, принадлежащие несвязанной продакшен-интеграции.
4. Убедитесь, что ваше развёртывание имеет публичный HTTPS базовый URL коннекторов. Вебхуки провайдеров не могут доставлять на `localhost` без защищённого туннеля разработки.
5. Откройте страницу **Коннекторы** сайта и выберите канал.

При сохранении Make Agent Fast вызывает провайдера для проверки отправленных учётных данных. Метка «подключено» означает, что проверка учётных данных и любое автоматическое обеспечение завершились; она не доказывает, что ручной шаг консоли Meta, Discord или Kakao был выполнен.

## Обращение с учётными данными [#обращение-с-учётными-данными]

Формы коннекторов принимают учётные данные провайдеров только из аутентифицированной панели или серверного публичного API. Секреты зашифрованы при хранении и никогда не возвращаются в ответах списка коннекторов. Относитесь к следующим значениям как к паролям:

* Токен бота Telegram
* Токены доступа Meta и секрет приложения
* Токен бота Discord
* REST API ключ Kakao и секрет бота

Не помещайте их в браузерный JavaScript, скриншоты, тикеты поддержки или систему контроля версий. URL вебхука и токен проверки Meta — значения конфигурации, предназначенные для копирования в соответствующую консоль провайдера; они не заменяют учётные данные провайдера.

## Подключение через API [#подключение-через-api]

Используйте серверный ключ MAF API с `connectors:write`. Объект `credentials` конкретного канала доступен только для записи. Ответ опускает секреты в открытом виде и включает URL вебхука, нужный для ручной настройки провайдера.

```bash
curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "config": { "reply_with_voice": false }
  }'
```

Сохранение того же канала заменяет его учётные данные/конфигурацию, сохраняя токен маршрутизации. Используйте [Аутентификацию API](/ru/docs/api/authentication), [Области и ошибки](/ru/docs/api/scopes-errors) и [Справочник API](/ru/docs/api/reference) для правил продакшен-интеграции.

## Тестируйте и наблюдайте [#тестируйте-и-наблюдайте]

Используйте тестового пользователя провайдера и реалистичный вопрос, зависящий от знаний агента. Подтвердите всё следующее:

* Провайдер принимает или проверяет конечную точку вебхука.
* Сообщение достигает агента и получает ожидаемый ответ.
* **Последнее сообщение** меняется на карточке коннектора.
* Ветка появляется в **Диалогах** с правильным каналом.
* Любое ограничение проверки/режима разработки провайдера понято перед публичным запуском.
* Голос тестируется отдельно от текста, когда канал его поддерживает.

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

## Отключение, ротация или удаление [#отключение-ротация-или-удаление]

**Отключение** останавливает обработку, сохраняя запись коннектора. Вебхук Telegram удаляется при отключении и регистрируется снова при включении; подписки провайдера, настроенные в консоли, остаются и тоже должны быть приостановлены на стороне провайдера при необходимости. **Удаление** удаляет коннектор Make Agent Fast и пытается наилучшими усилиями демонтировать провайдера, но не удаляет внешнее приложение, не отзывает его учётные данные и не стирает существующую историю диалогов.

Для ротации создайте новый токен провайдера, обновите коннектор, протестируйте его, затем отзовите старый токен. Если учётные данные были раскрыты, сначала отзовите их у провайдера и трактуйте интервал как инцидент безопасности.

## Частые сбои [#частые-сбои]

| Симптом                                    | Проверка                                                                                                                                 |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Учётные данные не проходят проверку        | Правильное приложение/бот, тип токена, срок действия, требуемое разрешение провайдера и скопированные символы                            |
| Проверка вебхука не работает               | Публичный HTTPS URL, точный токен проверки, правильный продукт провайдера и секрет подписи запросов                                      |
| Проверка успешна, но сообщения не приходят | Подписка на события, связь Страницы/номера/канала, режим приложения провайдера и состояние коннектора                                    |
| Текст работает, голос нет                  | Возможность канала, ключ речи/транскрибации, поддерживаемое аудио, разрешение медиа и срок загрузки провайдера                           |
| Ответы прекращаются после ротации          | Новые учётные данные сохранены, старые отозваны только после тестирования, и ручная подписка провайдера всё ещё указывает на этот вебхук |

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

---

# Telegram

Source: /ru/docs/connectors/telegram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; }
]"
/>

## Быстрая настройка [#быстрая-настройка]

Если на коннекторе Telegram доступно **Создать через QR**, выберите его, отсканируйте QR-код или нажмите **Открыть Telegram** и коснитесь **Создать бота** в боте настройки. Вернитесь в Make Agent Fast, проверьте имя пользователя бота и выберите **Подключить этого бота**. Копирование токена не требуется. Настройка истекает через 15 минут; её можно отменить и начать заново.

Если быстрая настройка недоступна, используйте **Подключение с токеном бота** ниже. Оба метода используют одни проверки подключения и подтверждение замены.

Форма создания предлагает отображаемое имя вашего агента и имя пользователя в формате `maf_<agent>_<random>_bot`. Оба редактируемы; случайная часть снижает столкновения имён, но финальную проверку доступности делает Telegram. Существующие боты не переименовываются.

После создания бот настройки отправляет кнопку **Подключить этого бота**, открывающую проверку подключения вашего агента с аутентификацией. Одно создание бота не подключает его. После успешного подтверждения **Открыть бота** ведёт к диалогу для тестирования. `/start` или `/help` восстанавливает активную настройку или показывает кнопки панели и гайда.

## Создайте и подготовьте бота вручную [#создайте-и-подготовьте-бота-вручную]

Следуйте официальному [Введению в ботов](https://core.telegram.org/bots) Telegram и [гайду BotFather](https://core.telegram.org/bots/features#botfather):

1. Откройте проверенный аккаунт **@BotFather** в Telegram.
2. Выполните `/newbot`, выберите отображаемое имя и уникальное имя пользователя, заканчивающееся на `bot`.
3. Скопируйте токен бота. Любой с этим токеном управляет ботом.
4. Опционально настройте фото, описание, текст «о боте» и локализованную справку команд в BotFather перед запуском.

Токен предназначен для Telegram Bot API; это не код входа Telegram, API ID или API хеш.

## Подключите в Make Agent Fast [#подключите-в-make-agent-fast]

Откройте страницу **Коннекторы** сайта, выберите **Telegram**, вставьте **Токен бота**, выберите, должны ли поддерживаемые ответы также озвучиваться, и нажмите **Подключить**.

Make Agent Fast вызывает Telegram `getMe` для проверки токена и отображения имени пользователя бота. Затем вызывает `setWebhook` с публичным HTTPS URL коннектора, секретным токеном проверки и `message`, `callback_query` и `my_chat_member` как принимаемыми типами обновлений. Существующие ожидающие обновления не отбрасываются.

Ручной шаг вебхука обычно не требуется. Остановите любой сервис опроса перед подключением. Если у бота есть другой получатель вебхука, проверьте и подтвердите его замену; Make Agent Fast не перехватывает его молча. Только один бот актуален на агента. Бот, уже привязанный к другому агенту, должен быть сначала отключён там.

## Протестируйте диалог [#протестируйте-диалог]

1. Откройте ссылку `t.me` бота с аккаунта Telegram не владельца.
2. Выберите **Запустить**; боты не могут начать диалог с пользователем.
3. Отправьте текстовый вопрос по знаниям.
4. Отправьте голосовое сообщение, если голос включён.
5. Убедитесь, что ответы приходят, **Последнее сообщение** меняется и ветка появляется в **Диалогах**.

Личные сообщения публичны по умолчанию: посетителям не нужно одобрение владельца. Ответы в группах выключены, пока владелец не включит **Отвечать в группах при упоминании или ответе**. Режим приватности Telegram и разрешения групп по-прежнему действуют. Сначала тестируйте личные сообщения.

## Поведение голоса [#поведение-голоса]

Telegram поддерживает входящий голос и исходящий голос в этом коннекторе. Входящий голос загружается и транскрибируется перед ходом агента. С включённым **Отвечать голосом** и доступным провайдером речи Make Agent Fast отправляет голосовой/аудио ответ в дополнение к тексту. Если транскрибация или речь не работает, попросите пользователя повторить текстом и проверьте ошибку коннектора.

## Ротация, отключение или удаление [#ротация-отключение-или-удаление]

Если токен раскрыт, сгенерируйте/отзовите его в BotFather немедленно, обновите коннектор заменой и протестируйте снова. Обновление учётных данных для того же бота сохраняет его настройки и приостановленный статус. Замена другим ботом требует подтверждения и держит историю прежнего бота отдельно.

Отключение останавливает ответы локально; удаление архивирует подключение и сохраняет его историю. Ни то, ни другое не удаляет бота Telegram и не вызывает `deleteWebhook`, что могло бы нарушить работу более нового получателя. Архивированные подключения игнорируют входящие сообщения. Быстро созданные боты могут обновить учётные данные после событий жизненного цикла менеджера, но приостановленный бот остаётся приостановленным, а смена владельца отключает подключение для проверки.

## Решение проблем [#решение-проблем]

| Симптом                                   | Решение                                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Токен отклонён при сохранении             | Скопируйте текущий токен BotFather; уберите пробелы и убедитесь, что он принадлежит этому боту                    |
| Сообщения достаются более старому сервису | Остановите опрос там, переподключитесь здесь и явно подтвердите любую замену получателя                           |
| Личные сообщения работают, групповые нет  | Включите групповые ответы, упомяните или ответьте боту и проверьте режим приватности Telegram и разрешения группы |
| Бот не пишет новому пользователю первым   | Ожидаемое поведение Telegram; попросите пользователя открыть бота и выбрать **Запустить**                         |
| Текст работает, голос нет                 | Проверьте ключи модели/транскрибации/речи и повторите с поддерживаемым голосовым сообщением Telegram              |

Никогда не вставляйте живой токен в документацию, исходный код, аналитику или скриншот поддержки.

---

# WhatsApp

Source: /ru/docs/connectors/whatsapp.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/connectors/overview&#x22;, label: &#x22;Все коннекторы&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; }
]"
/>

## Подготовьте приложение Meta и номер [#подготовьте-приложение-meta-и-номер]

Используйте официальный [гайд по началу работы с WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) Meta, чтобы создать или выбрать приложение Meta, добавить продукт WhatsApp и связать аккаунт WhatsApp Business и номер телефона.

Соберите эти три значения из одного приложения и номера:

| Поле Make Agent Fast   | Значение провайдера      | Примечания                                                                                                         |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **ID номера телефона** | Числовой Phone Number ID | Это не видимый номер `+` и не WABA ID                                                                              |
| **Токен доступа**      | Токен доступа Cloud API  | Временные токены панели истекают; используйте подходящий долгоживущий токен системного пользователя для продакшена |
| **Секрет приложения**  | Секрет приложения Meta   | 32-символьный шестнадцатеричный секрет для проверки подписи вебхука                                                |

Выдавайте только разрешения, нужные для номера и процесса сообщений. Держите ресурсы разработки/тестирования отдельно от продакшен-номера.

## Сохраните и проверьте учётные данные [#сохраните-и-проверьте-учётные-данные]

Откройте страницу **Коннекторы** сайта, выберите **WhatsApp**, введите все три значения, выберите **Отвечать голосом** при необходимости и нажмите **Подключить**.

Make Agent Fast проверяет номер через Graph API с токеном доступа плюс `appsecret_proof`; это ловит неправильный номер, токен или секрет приложения до начала трафика вебхуков. Затем карточка коннектора раскрывает уникальный **URL вебхука** и **Токен проверки**.

## Настройте вебхук Meta [#настройте-вебхук-meta]

В том же приложении Meta:

1. Откройте конфигурацию вебхука WhatsApp.
2. Вставьте **URL вебхука** коннектора как URL обратного вызова.
3. Вставьте **Токен проверки** коннектора точно; он чувствителен к регистру.
4. Завершите проверку.
5. Подпишите аккаунт/номер WhatsApp Business на поле вебхука `messages`.
6. Убедитесь, что приложение и бизнес-ресурсы доступны предполагаемым тестовым или продакшен-пользователям.

Токен проверки доказывает владение во время GET-вызова проверки. Запросы POST во время работы отдельно аутентифицируются подписью секрета приложения Meta; не заменяйте одно другим.

## Тестируйте текст и голос [#тестируйте-текст-и-голос]

Сначала отправьте сообщение с разрешённого тестового номера. В режиме разработки Meta незарегистрированные пользователи могут не достигать приложения. Подтвердите ветку и канал в **Диалогах** и следите за **Последним сообщением** на карточке коннектора.

Входящий текст и голос поддерживаются. С включённым **Отвечать голосом** и настроенной речью Make Agent Fast загружает сгенерированное аудио через Cloud API и отправляет его вместе с текстовым ответом. Изображения, локации, контакты и другие неподдерживаемые типы сообщений игнорируются.

## Готовность к продакшену [#готовность-к-продакшену]

Перед рекламой номера завершите проверку бизнеса Meta, проверку приложения, отображаемое имя, шаблоны и шаги политики сообщений, требуемые для вашего случая. Эти требования контролируются Meta и могут меняться независимо от Make Agent Fast.

Используйте продакшен-учётные данные с намеренным владельцем и процедурой истечения/ротации. Запишите, какое приложение Meta, системный пользователь, WABA и Phone Number ID принадлежат этому коннектору, чтобы оператор мог ротировать его без угадывания.

## Ротация или отключение [#ротация-или-отключение]

Создайте замещающий токен с тем же доступом к ресурсам, обновите коннектор, отправьте тестовое сообщение и только потом отзовите старый токен. Если секрет приложения меняется, обновите его в Make Agent Fast немедленно, иначе каждый подписанный входящий вебхук будет отклонён.

Отключение или удаление коннектора не отписывает и не удаляет конфигурацию вебхука Meta. Удалите подписку провайдера тоже при окончательном выводе номера из эксплуатации.

## Решение проблем [#решение-проблем]

| Симптом                                    | Решение                                                                                                                       |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Учётные данные отклонены                   | Убедитесь, что токен может читать точный Phone Number ID и секрет приложения из того же приложения                            |
| Meta не может проверить обратный вызов     | Используйте скопированный HTTPS URL и точный токен проверки; убедитесь, что коннектор всё ещё существует                      |
| Проверка успешна, но сообщения не приходят | Подпишите `messages`, проверьте связь WABA/номера, режим приложения, доступ тестовых пользователей и логи доставки провайдера |
| Вебхуки возвращают неавторизовано          | Введите правильный секрет приложения заново; подписи POST Meta не используют токен проверки                                   |
| Исходящие ответы не работают               | Проверьте срок токена, разрешения номера, политику/окно получателя и ошибки Graph API                                         |
| Текст работает, аудио нет                  | Проверьте ключи провайдеров транскрибации/речи и доступ токена к загрузке/скачиванию медиа                                    |

Никогда не раскрывайте токен доступа или секрет приложения в браузерном коде. Используйте публичный API только с доверенного сервера при автоматизации создания коннекторов.

---

# Astro

Source: /ru/docs/embed/astro.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Подготовьте origin развёртывания [#подготовьте-origin-развёртывания]

Включите встраивание для агента Make Agent Fast и разрешите точные origin разработки, предпросмотра и продакшена Astro. Важна финальная scheme/hostname/port в браузере, а не хост сборки или URL репозитория.

## Добавьте в общий макет [#добавьте-в-общий-макет]

Разместите стандартный внешний загрузчик непосредственно перед `</body>` в макете Astro, который должен владеть загрузчиком.

```astro
---
// src/layouts/BaseLayout.astro
---

<html lang="en">
  <body>
    <slot />

    <script
      is:inline
      src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
      async
    ></script>
  </body>
</html>
```

`is:inline` говорит Astro сохранить внешний тег скрипта и его `data-*` атрибуты вместо сборки/трансформации. Загрузчик остаётся публичным и независимым от фреймворка; не импортируйте его в серверный модуль.

## Ограничьте выбранными страницами [#ограничьте-выбранными-страницами]

Используйте вложенный макет или включайте тег только на выбранных страницах `.astro`. Не размещайте один и тот же тег и в базовом макете, и на странице. Загрузчик игнорирует дублирующий корень того же slug, но дублированный HTML усложняет анализ навигации и снятия.

Если включены клиентские view transitions Astro, проверяйте и прямые загрузки страниц, и навигацию внутри приложения. Для агента на весь сайт предпочтителен постоянный общий макет. Для поведения по маршруту удаляйте и скрипт, и `maf-embed-root-YOUR_SITE_SLUG` при уходе с маршрута, а позже вставляйте свежий скрипт.

## Настройте CSP и согласие [#настройте-csp-и-согласие]

Заголовки статичного хостинга всё равно управляют браузером. Разрешите `https://makeagent.fast` в `script-src`, `frame-src` и соответствующей политике соединений. Если менеджер согласия блокирует скрипт, загружайте тег только после нужного согласия, а не ослабляйте CSP и не обходите согласие.

## Проверьте собранный результат [#проверьте-собранный-результат]

1. Запустите продакшен-сборку Astro и проверьте в итоговом HTML сохранённый тег `data-agent`.
2. Откройте развёрнутую страницу в приватном окне.
3. Убедитесь, что есть один корень встраивания и успешные запросы загрузчика/iframe.
4. Переходите по маршрутам Astro и подтвердите нужное сохранение.
5. Отправьте реальное сообщение и проверьте поведение на мобильном и с микрофоном.

## Решение проблем [#решение-проблем]

| Симптом                                            | Решение                                                      |
| -------------------------------------------------- | ------------------------------------------------------------ |
| Собранный HTML теряет/меняет атрибуты              | Добавьте `is:inline` к внешнему скрипту                      |
| Выводятся два тега скрипта                         | Держите установку в одном владеющем макете/странице          |
| Клиентская навигация отличается от прямой загрузки | Проверьте view transitions и выберите постоянный общий макет |
| Работает в dev, но не на статичном хосте           | Добавьте точный продакшен-origin и CSP-заголовки хостинга    |
| Голос не работает                                  | Настройте HTTPS, разрешение браузера и Permissions Policy    |

Npm-адаптер для Astro пока не опубликован; используйте размещённый загрузчик, показанный здесь.

---

# Cafe24

Source: /ru/docs/embed/cafe24.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Cafe24 (카페24) — корейская коммерческая платформа, дизайн витрины которой редактируется как HTML. Установите загрузчик в общий макет используемого дизайна. Приложения Make Agent Fast в магазине приложений Cafe24 пока нет. Названия меню указаны по состоянию на 2026-09; если пункт переехал, ищите настройку по её назначению, а не по точному пути.

## Добавьте загрузчик [#добавьте-загрузчик]

1. В панели Make Agent Fast включите **Встраивание** и добавьте в разрешённый список все origin витрины — адрес магазина `cafe24.com` и ваш собственный домен, а также мобильный адрес, если он отличается.
2. Откройте управление дизайном и запустите редактирование HTML для действующего дизайна. Сначала продублируйте или сохраните резервную копию дизайна — вы редактируете исходный код витрины.
3. В общем файле макета, который подключается на каждой странице, вставьте сгенерированный сниппет непосредственно перед закрывающим тегом `</body>`.
4. Сохраните, примените дизайн к витрине и повторите для мобильного дизайна, если магазин ведёт PC- и мобильную версии отдельно.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Если вы не нашли файл макета, вставьте сниппет в блок footer вашей темы — подойдёт любой модуль, который выводится на каждой странице, лишь бы он подключался один раз.

## Проверьте [#проверьте]

1. Откройте витрину в приватном окне и по PC-адресу, и по мобильному адресу.
2. Убедитесь, что origin в адресной строке совпадает с разрешённым, включая `www`, если домен на него перенаправляет.
3. Убедитесь, что `embed.js` возвращает `200` в панели Network и существует один элемент `data-maf-embed="YOUR_SITE_SLUG"`.
4. Задайте реальный вопрос и убедитесь, что сообщение появилось в разделе **Диалоги**.

## Решение проблем [#решение-проблем]

| Симптом                                                       | Вероятная причина                             | Решение                                                                   |
| ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
| Работает на PC, но не на мобильном                            | У мобильного дизайна собственный файл макета  | Добавьте сниппет и в мобильный дизайн                                     |
| Загрузчик пропал после смены дизайна                          | Применён дизайн без сниппета                  | Добавьте его повторно в макет дизайна, который сейчас обслуживает магазин |
| Загрузчик перекрывает корзину или фиксированную нижнюю панель | Два фиксированных элемента занимают один угол | Смените угол загрузчика через `data-position`                             |

Не помещайте ключ API, номер заказа или данные клиентов в атрибуты `data-*`. В разделе [Безопасность и CSP](/ru/docs/embed/security) описаны разрешённые origin и Content Security Policy для витрин, где она задана.

---

# Framer

Source: /ru/docs/embed/framer.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Доступность код-компонента [#доступность-код-компонента]

Скопируйте `integrations/framer/MakeAgentFast.tsx` в код-компонент Framer и выберите опубликованного агента. Исходник предоставляет настройки URL платформы, позиции и подписи. Это копируемый вручную исходный код, а не опубликованный компонент Framer Marketplace. URL листинга появится здесь только после того, как уполномоченный владелец опубликует и проверит его.

## Пользовательский код [#пользовательский-код]

Добавьте стандартный загрузчик в **Site settings → Custom code** в конец body.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Опубликуйте перед проверкой. Холст и хост предпросмотра Framer могут использовать origin, отличные от живого опубликованного хоста.

---

# Ghost

Source: /ru/docs/embed/ghost.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Откройте **Settings → Code injection** и добавьте скрипт в подвал сайта.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Внедрение кода на уровне поста используйте только когда агент должен появляться на выбранных публикациях. Если вы вместо этого правите тему, разместите загрузчик в `default.hbs` перед `</body>` и перепроверяйте его после обновлений темы.

Разрешите публичный origin публикации и очистите edge-кэш перед проверкой изменённого slug.

---

# HTML и JavaScript

Source: /ru/docs/embed/html.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Подготовьте сайт [#подготовьте-сайт]

Откройте настройки **Встраивание** агента, включите встраивание и добавьте финальный origin страницы-хоста. Разработку и продакшен добавляйте отдельно; `http://localhost:3000`, `https://example.com` и `https://www.example.com` не совпадают друг с другом.

## Установите скрипт [#установите-скрипт]

Вставьте загрузчик непосредственно перед закрывающим тегом `</body>` на каждой странице, где должен показываться загрузчик. Меняйте только публичный slug сайта и необязательные значения оформления.

```html
<script
  src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

`data-agent` обязателен. Slug публичен; ключ API в этом теге не нужен. Сохраните параметр `?v=` из сниппета панели. Необязательные `data-label`, `data-accent` (`#RGB` / `#RRGGBB`), `data-locale` (`en` | `ko` | `uz` | `ru`) и `data-theme` (`light` | `dark`) описаны в [Обзоре встраивания](/ru/docs/embed/overview). Опустите их, чтобы унаследовать сохранённый внешний вид и автоматическое поведение темы.

## Выберите размещение: на весь сайт или на отдельные страницы [#выберите-размещение-на-весь-сайт-или-на-отдельные-страницы]

Для общего серверного шаблона разместите скрипт в глобальном макете/подвале. Для выбранных страниц включайте его только в эти шаблоны. Загружайте один и тот же slug один раз на документ; дубли одного slug игнорируются, но удаление дублей делает владение и снятие предсказуемыми.

Не вставляйте сниппет в санитайзер HTML или поле rich-text, которое вырезает `<script>`. Убедитесь, что отрендеренный исходный код страницы или панель Elements всё ещё содержит тег.

## Удаление и повторный монтаж в SPA [#удаление-и-повторный-монтаж-в-spa]

Удаление скрипта после его выполнения не убирает уже созданный загрузчик. Клиентское приложение с маршрутизацией должно удалить и скрипт, и корень с slug перед повторным монтажом:

```js
const slug = "YOUR_SITE_SLUG";
document.getElementById("maf-agent")?.remove();
document.getElementById(`maf-embed-root-${slug}`)?.remove();
```

Лучше держать один общий корень смонтированным при клиентской навигации, чтобы активный диалог не терялся. Если корень удалён, добавьте свежий скрипт `embed.js`, чтобы создать его снова.

## Проверьте в браузере [#проверьте-в-браузере]

1. Откройте развёрнутую страницу в приватном окне.
2. Убедитесь, что `embed.js` возвращает `200` и не заблокирован CSP/согласием.
3. Убедитесь, что существует один корень `[data-maf-embed="YOUR_SITE_SLUG"]`.
4. Откройте загрузчик и убедитесь, что iframe `/embed/YOUR_SITE_SLUG` загружается.
5. Отправьте вопрос и проверьте цепочку в разделе **Диалоги**.
6. Проверьте мобильную ширину и разрешение на микрофон, когда включён голос.

## Решение проблем [#решение-проблем]

| Симптом                                             | Решение                                                                      |
| --------------------------------------------------- | ---------------------------------------------------------------------------- |
| Консоль предупреждает об отсутствующем `data-agent` | Поставьте атрибут именно на тег `embed.js`                                   |
| Скрипт есть, загрузчика нет                         | Проверьте переключатель встраивания, точный origin, CSP и состояние согласия |
| Работает только на одном хосте                      | Добавьте каждый фактический scheme/host/port в разрешённый список            |
| Стиль отличается от ожидаемого                      | Проверьте `data-accent`, `data-theme` и сохранённый вид сайта                |
| Голос не работает внутри iframe                     | Разрешите микрофон в браузере и в Permissions Policy сайта                   |

Никогда не проксируйте и не копируйте загрузчик в непроверенный локальный форк; используйте размещённый скрипт, чтобы проверка origin и исправления оставались актуальными.

---

# Imweb

Source: /ru/docs/embed/imweb.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Imweb (아임웹) — корейский конструктор сайтов, которым пользуются многие небольшие магазины и студии. Загрузчик устанавливается через собственную настройку вставки кода Imweb. Приложения Make Agent Fast в каталоге Imweb нет. Названия меню указаны по состоянию на 2026-09; если пункт переехал, ищите настройку по её назначению, а не по точному пути.

## Добавьте загрузчик [#добавьте-загрузчик]

1. В панели Make Agent Fast включите **Встраивание** и добавьте в разрешённый список все origin, которые обслуживает Imweb — ваш домен и бесплатный адрес `imweb.me`, если вы им ещё пользуетесь.
2. Откройте настройки сайта и найдите раздел вставки кода: поля, которые добавляют разметку в `<head>` каждой страницы или в конец body. Доступность зависит от вашего тарифа Imweb.
3. Вставьте сгенерированный сниппет в поле head. Загрузчик работает с `async`, поэтому подходят и head, и конец body.
4. Сохраните и примените изменение к живому сайту, затем перезагрузите витрину в новой вкладке.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Если вы не нашли эту настройку, вставьте сниппет в блок footer вашей темы: HTML-виджет, размещённый в секции подвала, работает на каждой странице, использующей эту секцию.

## Проверьте [#проверьте]

1. Откройте опубликованный URL в приватном окне, а не в редакторе Imweb. Режимы редактирования и предпросмотра могут подавлять внедрённые скрипты.
2. Убедитесь, что origin в адресной строке совпадает с разрешённым, включая `www`, если домен на него перенаправляет.
3. Убедитесь, что `embed.js` возвращает `200` в панели Network и существует один элемент `data-maf-embed="YOUR_SITE_SLUG"`.
4. Задайте реальный вопрос и убедитесь, что сообщение появилось в разделе **Диалоги**.

## Решение проблем [#решение-проблем]

| Симптом                                         | Вероятная причина                                     | Решение                                          |
| ----------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------ |
| На собственном домене ничего не загружается     | В разрешённый список добавлен только адрес `imweb.me` | Добавьте также точный origin собственного домена |
| Загрузчик появляется дважды                     | Сниппет стоит и в поле head, и в HTML-виджете подвала | Оставьте одну копию — в поле head                |
| Загрузчик перекрывает плавающую кнопку магазина | Два фиксированных элемента занимают один угол         | Смените угол загрузчика через `data-position`    |

Если магазин использует баннер согласия или блокировщик скриптов, отнесите встраивание к нужной категории по вашей политике согласия и загружайте соответственно. Разрешённые origin перечислены в разделе [Безопасность и CSP](/ru/docs/embed/security).

---

# Notion и Linktree

Source: /ru/docs/embed/notion-linktree.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Страницы Notion и профили Linktree не предоставляют поверхность для произвольного JavaScript на весь сайт. Вместо этого делитесь собственной публичной страницей агента.

## Добавьте ссылку [#добавьте-ссылку]

1. На последнем шаге онбординга включите **Публичная страница** в разделе **Проверка на телефоне**. Эта настройка также доступна в параметрах отображения агента.
2. Скопируйте фактический URL публичной страницы, показанный Make Agent Fast. Не выдумывайте slug агента или домен.
3. Добавьте ссылку или закладку в Notion либо ссылку Linktree вроде **Поговорите с нашим агентом**.
4. Откройте ссылку на телефоне. Любой, у кого есть ссылка, может писать, пока страница включена; выключение делает страницу недоступной.

Вашему клиентскому сайту не нужен скрипт, чтобы эта ссылка работала. Если хотите ссылаться на собственный сайт, сначала установите там виджет и используйте URL этой страницы. Обычная ссылка надёжнее, чем размещение страницы внутри iframe другой платформы, который может ограничивать доступ к микрофону и раскладку.

---

# Обзор встраивания

Source: /ru/docs/embed/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/html&#x22;, label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/react-next&#x22;, label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/ru/docs/embed/vue-nuxt&#x22;, label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/ru/docs/embed/sveltekit&#x22;, label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/ru/docs/embed/astro&#x22;, label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/ru/docs/embed/wordpress&#x22;, label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/ru/docs/embed/shopify&#x22;, label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/ru/docs/embed/webflow&#x22;, label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/ru/docs/embed/framer&#x22;, label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/ru/docs/embed/wix&#x22;, label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/ru/docs/embed/squarespace&#x22;, label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/ru/docs/embed/ghost&#x22;, label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/ru/docs/embed/notion-linktree&#x22;, label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/ru/docs/embed/tilda&#x22;, label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/imweb&#x22;, label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/cafe24&#x22;, label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: &#x22;CSP&#x22;, icon: &#x22;shield&#x22; }
]"
/>

## Как работает встраивание [#как-работает-встраивание]

`embed.js` добавляет один фиксированный загрузчик в документ сайта. Первый клик посетителя открывает лениво загружаемый iframe с `https://makeagent.fast`; агент и диалог остаются изолированными от страницы внутри этого фрейма. CSS сайта не может перестилизовать чат, а контент агента не может переписать документ сайта.

Загрузчик публичен и **не** использует ключ API. Доступ контролируется переключателем **Встраивание** и точным разрешённым списком родительских origin. Slug сайта — идентификатор, а не секрет.

## Предварительные условия [#предварительные-условия]

Прежде чем копировать код:

1. Создайте и проверьте агента в панели управления.
2. Используйте сгенерированный сниппет агента; публиковать его отдельную публичную страницу не обязательно.
3. Откройте страницу **Встраивание** сайта и включите переключатель **Встраивание**.
4. Добавьте каждый родительский origin, который будет выводить загрузчик.
5. Сохраните и скопируйте сгенерированный сниппет.

Origin содержит только схему, имя хоста и необязательный порт. Пути в нём нет. Это четыре разных origin — добавляйте их отдельно, если используете:

```text
https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000
```

Не вводите `https://example.com/pricing`, `*.example.com` или завершающий шаблон. Если продакшен перенаправляет с основного домена на `www`, разрешайте тот origin, который остаётся в адресной строке после перенаправления.

## Установите загрузчик [#установите-загрузчик]

Поставьте один скрипт перед закрывающим тегом `</body>` или используйте браузерный жизненный цикл, рекомендованный гайдом вашего фреймворка.

Страница **Встраивание** в панели копирует именно эту форму (slug сайта, позиция, необязательная подпись и параметр `?v=` против кэша). Сохраните `async`. Сохраните параметр `?v=` из сниппета, чтобы сайты не закрепляли устаревший загрузчик.

```html
<script
  src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

Обязателен только `data-agent`. Необязательные атрибуты, которые загрузчик действительно читает:

```html
<script
  src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>
```

Не помещайте ключ MAF API, ключ провайдера, токен коннектора, идентичность посетителя или приватные данные клиентов в атрибуты `data-*`. Не выдумывайте атрибуты вроде `data-api-key`, `data-z-index`, `data-offset` или `data-delay`. `data-maf-bootstrapped` выставляет сам загрузчик.

## Настройте атрибуты [#настройте-атрибуты]

Читаются только из тега `embed.js`. Iframe принимает акценты только в hex-формате.

| Атрибут         | Допустимое значение                                                                                        | По умолчанию            | Действие                                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| `data-agent`    | Slug сайта агента                                                                                          | Обязателен              | Выбирает сайт и агента. Отсутствует → предупреждение в консоли, загрузчика нет                             |
| `data-position` | `bottom-left`, `bottom-right`, `top-left`, `top-right` (`left` / `right` по-прежнему означают нижние углы) | `right` (нижний правый) | Любое другое значение трактуется как нижний правый угол                                                    |
| `data-label`    | Обычный текст                                                                                              | Только иконка           | Видимый текст загрузчика и доступное имя. Экранируйте `"`, `<`. Интерфейс панели ограничивает 40 символами |
| `data-accent`   | `#RGB` или `#RRGGBB`                                                                                       | Сохранённый вид сайта   | Переопределение цвета загрузчика со стороны сайта; не-hex значения игнорируются в iframe                   |
| `data-locale`   | `en`, `ko`, `uz` или `ru`                                                                                  | Основной язык агента    | Язык, на котором агент открывается на этой странице, — из его включённых языков                            |
| `data-theme`    | `light` или `dark`                                                                                         | Фон сайта, иначе ОС     | Другие значения игнорируются                                                                               |

Без `data-theme` загрузчик пробует фон сайта, затем возвращается к предпочтению ОС посетителя. Он также передаёт шрифт сайта во фрейм и запрашивает актуальный вид загрузчика. Неудавшийся запрос вида не блокирует загрузчик — сохраняется безопасный стиль по умолчанию. Сохранения внешнего вида в панели обновляют этот запрос без повторной публикации сайта.

## Поведение во время работы [#поведение-во-время-работы]

* Загружайте скрипт один раз на документ. Повторение того же slug идемпотентно и по-прежнему даёт один корень `maf-embed-root-YOUR_SITE_SLUG`.
* Разные агенты могут сосуществовать на одном документе. Загрузчик помечает каждый обработанный скрипт как `data-maf-bootstrapped`, поэтому асинхронный запасной путь инициализирует каждый отдельный тег `data-agent` ровно один раз.
* Iframe ленив и скрыт, пока посетитель его не откроет. Он запрашивает разрешения на микрофон, автовоспроизведение и запись в буфер только через модель разрешений iframe браузера.
* В приложении с клиентской маршрутизацией монтируйте загрузчик в самый верхний макет, который должен им владеть, чтобы смена маршрутов не перезагружала диалог.
* Удаление только элемента скрипта не убирает уже созданный загрузчик. Для снятия по маршруту удалите также соответствующий элемент `maf-embed-root-...`. Чтобы смонтировать заново, перезагрузите скрипт после снятия.
* Фрейм и загрузчик обмениваются только сообщениями жизненного цикла в собственном пространстве имён. Загрузчик отклоняет сообщения не с origin Make Agent Fast и не от текущего slug сайта.

## Проверьте установку [#проверьте-установку]

Проверяйте публичную страницу, а не только предпросмотр в редакторе конструктора:

1. Откройте развёрнутый URL в приватном окне и убедитесь, что его точный origin разрешён.
2. Убедитесь, что `https://makeagent.fast/embed.js?v=20260728-widget-v2` возвращает `200` в панели Network.
3. Убедитесь, что существует ровно один элемент с `data-maf-embed="YOUR_SITE_SLUG"`.
4. Откройте загрузчик и убедитесь, что запрос iframe к `/embed/YOUR_SITE_SLUG` успешен.
5. Отправьте реальный вопрос и убедитесь, что он появился в разделе **Диалоги**.
6. Проверьте узкое мобильное окно и, если включено, разрешение на микрофон.

## Диагностируйте отсутствующий загрузчик [#диагностируйте-отсутствующий-загрузчик]

| Симптом                                       | Вероятная причина                                             | Решение                                                            |
| --------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
| Консоль предупреждает `missing data-agent`    | Атрибут slug отсутствует или стоит на другом скрипте          | Поставьте `data-agent` на тег `embed.js`                           |
| `embed.js` заблокирован                       | CSP или менеджер согласия отклонил скрипт                     | Разрешите origin скрипта или загружайте его после нужного согласия |
| Загрузчик появляется, но фрейм не загружается | Встраивание выключено или родительский origin другой          | Перепроверьте встраивание и разрешённые сайты в панели             |
| Работает на localhost, но не в продакшене     | Разрешён только origin разработки                             | Добавьте точный развёрнутый HTTPS origin                           |
| Появляются два разных агента                  | Документ загружает два разных slug                            | Оставьте только нужный slug сайта                                  |
| Чат открывается, но голос не работает         | Разрешение браузера или Permissions Policy блокирует микрофон | Следуйте разделу [Безопасность и CSP](/ru/docs/embed/security)     |

## Выберите гайд по установке [#выберите-гайд-по-установке]

Используйте [HTML и JavaScript](/ru/docs/embed/html) для обычного тега скрипта. Для React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace или Ghost выберите соответствующий гайд в боковой панели. Платформы, не допускающие произвольный JavaScript, — например, многие поверхности Notion и Linktree — могут ссылаться на включённую **Публичную страницу** агента, доступную на последнем шаге онбординга и в настройках агента. Ещё один вариант — клиентский сайт с встраиванием.

## Для кодирующих агентов [#для-кодирующих-агентов]

Устанавливаете это на клиентский сайт через Claude Code, Cursor или Codex? Скопируйте `skills/embed-agent/SKILL.md` из репозитория Make Agent Fast в `.cursor/skills/embed-agent/` или `.claude/skills/embed-agent/`. Этот файл — рецепт установки (атрибуты, CSP, размещение). Эта страница остаётся гайдом для людей.

---

# React и Next.js

Source: /ru/docs/embed/react-next.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Подготовьте origin и область [#подготовьте-origin-и-область]

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

## Next.js App Router [#nextjs-app-router]

Используйте `next/script` в компоненте, который рендерит макет, владеющий загрузчиком. Slug можно раскрывать; не используйте ключ API или секретную переменную окружения.

```tsx
import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
    />
  );
}
```

Отрендерьте `<AgentEmbed />` один раз в `app/layout.tsx` для агента на весь сайт или во вложенном макете для группы маршрутов. Не рендерьте отдельную копию из каждого компонента страницы. `afterInteractive` избегает серверного доступа к DOM и не блокирует разбор исходного HTML.

В Next.js Pages Router отрендерьте тот же компонент один раз из `pages/_app.tsx` для поведения на весь сайт. Рендер из отдельной страницы уместен, только когда уход со страницы должен убирать агента; в этом случае используйте явный паттерн эффекта/очистки ниже, потому что загруженный внешний скрипт уже создал DOM вне дерева React.

## React без Next.js [#react-без-nextjs]

Создавайте скрипт в эффекте. Стабильный ID скрипта предотвращает повторную вставку в Strict Mode разработки. Если компонент привязан к маршруту, очистка должна удалить и скрипт, и корень, созданный загрузчиком.

```tsx
import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}
```

Для загрузчика на весь сайт смонтируйте этот компонент выше роутера и не делайте размонтирование по маршрутам. Сохранение корня сохраняет iframe и диалог между переходами.

## Конфигурация окружения [#конфигурация-окружения]

Публичная переменная времени сборки может хранить **slug**, потому что он не секретный. Проверяйте его перед рендером и держите настоящие ключи MAF API и учётные данные провайдеров только на сервере. Отсутствующий slug заставляет загрузчик предупредить и завершиться, не создавая загрузчик.

Если ваше приложение обслуживает разных клиентских арендаторов из одной сборки React, не меняйте `data-agent` на уже выполненном скрипте. Дайте текущему арендатору один стабильный slug, удалите корень старого slug при аутентифицированной смене арендатора и затем смонтируйте свежий скрипт. Никогда не позволяйте недоверенному параметру запроса выбирать slug другого арендатора.

## Проверьте гидратацию и навигацию [#проверьте-гидратацию-и-навигацию]

1. Загрузите публичный маршрут напрямую и убедитесь, что загрузчик один.
2. Переходите на клиенте по маршрутам, где он должен сохраняться.
3. При установке на вложенный маршрут выйдите из него и убедитесь, что скрипт и корень исчезли, затем вернитесь и проверьте один свежий загрузчик.
4. Проверьте Network/CSP и отправьте реальное сообщение.
5. Запустите продакшен-сборку; одного Strict Mode разработки недостаточно для финального поведения.

## Решение проблем [#решение-проблем]

| Симптом                                             | Решение                                                                                     |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `document is not defined`                           | DOM-код выполнился во время SSR; перенесите его в `useEffect` или используйте `next/script` |
| Появляются два загрузчика/агента                    | Смонтировано несколько slug или компонентов; оставьте один владеющий макет                  |
| Загрузчик остаётся после ухода с маршрута           | Удаляйте `maf-embed-root-SLUG` в очистке, а не только скрипт                                |
| Загрузчик исчезает при каждой навигации             | Монтируйте выше в дереве макета/роутера                                                     |
| Работает локально, но не в предпросмотре/продакшене | Разрешите точный origin каждого развёртывания                                               |

Npm-адаптер для React/Next пока не опубликован; эти примеры используют поддерживаемый публичный загрузчик, не зависящий от REST.

---

# Безопасность и CSP

Source: /ru/docs/embed/security.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; },
{ href: &#x22;/ru/docs/build/appearance&#x22;, label: 'Внешний вид', icon: &#x22;spark&#x22; }
]"
/>

## Разрешённый список origin [#разрешённый-список-origin]

Встраивание отказывает по умолчанию, пока оно не включено и точный родительский origin браузера не разрешён. Origin — это `scheme://hostname[:port]`; пути и строки запроса в него не входят.

| Страница сайта                          | Значение для списка                |
| --------------------------------------- | ---------------------------------- |
| `https://example.com/pricing`           | `https://example.com`              |
| `https://www.example.com/help`          | `https://www.example.com`          |
| `https://preview.example.com:8443/demo` | `https://preview.example.com:8443` |
| `http://localhost:3000`                 | `http://localhost:3000`            |

Добавляйте продакшен-, предпросмотр- и локальные origin отдельно. Не добавляйте шаблон-звёздочку ради исправления ошибки установки: иначе любой, кто скопирует публичный slug, сможет встроить агента и расходовать кредиты сайта.

## Content Security Policy [#content-security-policy]

Загрузчику нужно разрешение на скрипт, виджету — на фрейм, а запросу внешнего вида загрузчика может понадобиться разрешение на соединение. Объедините эти источники с существующими директивами сайта; не заменяйте зрелую политику этим минимальным примером.

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Если сайт использует `script-src-elem`, добавьте `https://makeagent.fast` и туда. Внешнему загрузчику не нужен `unsafe-inline`, но собственный фреймворк сайта может иметь отдельные требования к nonce или хешам. Политика report-only полезна во время тестирования:

```http
Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Когда консоль браузера сообщает о нарушении CSP, меняйте названную директиву — а не `default-src` в ширину — и перепроверяйте публичную страницу.

## Микрофон и разрешения браузера [#микрофон-и-разрешения-браузера]

Загрузчик создаёт iframe с `allow="microphone; autoplay; clipboard-write"`. Более строгая Permissions Policy на уровне сайта всё равно может переопределить это разрешение. Если голос включён, разрешите origin фрейма Make Agent Fast в ответе сайта:

```http
Permissions-Policy: microphone=(self "https://makeagent.fast")
```

Посетитель также должен выдать доступ к микрофону в браузере. Проверяйте по HTTPS; браузеры обычно ограничивают доступ к микрофону на незащищённых публичных origin. Текстовый чат не требует разрешения на микрофон.

## Граница сообщений и фрейма [#граница-сообщений-и-фрейма]

Загрузчик принимает только сообщения `maf:ready`, `maf:open`, `maf:close` и сообщения жизненного цикла темы, связанные с текущим slug сайта. Входящие сообщения фрейма проверяются против `https://makeagent.fast`. Не копируйте загрузчик в собственный бандл и не удаляйте эту проверку origin.

Код страницы сайта не должен пытаться залезть в DOM iframe. Фрейм cross-origin по замыслу, и поддерживаемая поверхность интеграции — загрузчик плюс его документированные атрибуты `data-*`.

## Секреты и идентичность посетителей [#секреты-и-идентичность-посетителей]

Slug сайта и URL загрузчика публичны. Всё остальное держите вне исходного кода страницы:

* Никогда не добавляйте ключ MAF API, токен OAuth, ключ AI-провайдера, токен коннектора или секрет вебхука в сниппет.
* Никогда не встраивайте секрет в бандл JavaScript и не раскрывайте его через `NEXT_PUBLIC_*`, `VITE_*` или похожие браузерные переменные окружения.
* Используйте серверную интеграцию API, когда приложению нужно создавать сайты, обновлять агентов или получать приватные данные рабочего пространства.
* Не помещайте адреса электронной почты, ID аккаунтов и другие данные посетителей в `data-label`, `data-locale` или параметры запроса.

## Согласие, конфиденциальность и хранение [#согласие-конфиденциальность-и-хранение]

Отнесите встраивание к категории по вашей политике конфиденциальности и согласия. Если менеджер согласия блокирует необязательные сторонние скрипты, загружайте `embed.js` только после нужного согласия. До этого показывайте обычную ссылку или отключённый плейсхолдер вместо обхода менеджера.

Сообщайте посетителям, когда сценарий использует ИИ, запись микрофона, сбор заявок, аналитику или внешнего провайдера сообщений — как требует ваша политика и применимый закон. Перед запуском убедитесь в процессе хранения и удаления диалогов на сайте; отключение или удаление встраивания само по себе не удаляет существующие диалоги.

## Чек-лист безопасности при запуске [#чек-лист-безопасности-при-запуске]

* Клиентский сайт развёрнут, и его встроенный агент включён и проверен.
* Разрешены только точные, предназначенные родительские origin.
* CSP сайта разрешает скрипт, фрейм и запрос внешнего вида без широких шаблонов.
* Микрофон разрешён только если голос включён и проверен по HTTPS.
* Ни одно учётное или приватное значение посетителя не появляется в HTML, собранном бандле или логах браузера.
* Поведение менеджера согласия проверено до и после согласия.
* Скопированный сниппет не работает на origin вне разрешённого списка.

---

# Shopify

Source: /ru/docs/embed/shopify.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Доступность расширения темы [#доступность-расширения-темы]

Исходник расширения темы находится в `integrations/shopify`. Это шаблон для разработки, а не публичное приложение Shopify App Store. Авторизованный аккаунт Partner должен поместить его в оболочку приложения, развернуть и пройти проверку Shopify, прежде чем мерчанты смогут установить его из App Store.

## Custom Liquid [#custom-liquid]

В **Online Store → Themes → Customize** добавьте блок Custom Liquid там, где он поддерживается, или отредактируйте `theme.liquid` и разместите скрипт перед `</body>`.

```liquid
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Разрешите канонический origin витрины. Превью-хосты могут отличаться от живого `myshopify.com` или собственного хоста магазина — их нужно добавлять отдельно для тестирования.

## Смена темы [#смена-темы]

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

---

# Squarespace

Source: /ru/docs/embed/squarespace.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Для загрузчика на весь сайт вставьте сниппет в **Settings → Advanced → Code Injection → Footer** — там, где это поддерживает ваш тариф Squarespace.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

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

Если конфигурация cookie-согласия блокирует сторонние скрипты, отнесите встраивание к категории и загружайте согласно вашей политике согласия.

---

# SvelteKit

Source: /ru/docs/embed/sveltekit.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Подготовьте origin [#подготовьте-origin]

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

## Создайте компонент [#создайте-компонент]

`onMount` выполняется только в браузере. Возвращайте функцию очистки, когда владеющий макет/компонент может размонтироваться.

```svelte
<script lang="ts">
  import { onMount } from "svelte";

  const slug = "YOUR_SITE_SLUG";

  onMount(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  });
</script>
```

Смонтируйте компонент один раз из `src/routes/+layout.svelte` для всего приложения. Для группы маршрутов разместите его в `+layout.svelte` этой группы; очистка удалит загрузчик, когда посетитель уходит из группы.

## Используйте конфигурацию безопасно [#используйте-конфигурацию-безопасно]

Публичный slug сайта может быть публичным значением окружения SvelteKit, потому что он не учётные данные. Не используйте `$env/static/public` или браузерный код для ключей MAF API, ключей AI-провайдеров или секретов коннекторов. Держите их в серверных модулях/маршрутах.

## Сохранение или сброс состояния диалога [#сохранение-или-сброс-состояния-диалога]

Удержание компонента в корневом макете сохраняет один и тот же iframe между клиентскими переходами. Очистка по маршруту намеренно сбрасывает этот iframe и его текущее состояние на странице. Выберите одно поведение вместо перемонтирования на каждой странице.

## Проверьте продакшен-сборку [#проверьте-продакшен-сборку]

1. Запустите продакшен-адаптер/сборку SvelteKit.
2. Загрузите публичный маршрут напрямую и убедитесь, что загрузчик/корень один.
3. Перейдите внутрь владеющего макета и из него.
4. Проверьте Network/CSP и точный родительский origin.
5. Проверьте реальное сообщение, узкое окно и микрофон, если он включён.

## Решение проблем [#решение-проблем]

| Симптом                                  | Решение                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| Ошибка `document` во время SSR           | Держите весь код загрузчика внутри `onMount`                                             |
| Загрузчик остаётся после ухода из макета | Верните очистку и удалите созданный корень                                               |
| Диалог сбрасывается на каждой странице   | Монтируйте в постоянный родительский `+layout.svelte`                                    |
| Защита от дублей мешает новому монтажу   | Убедитесь, что предыдущая очистка удалила старый корень перед добавлением нового скрипта |
| Падает только в продакшене               | Разрешите финальный HTTPS origin и проверьте CSP-заголовки адаптера                      |

Npm-адаптер для SvelteKit пока не опубликован; размещённый скрипт — поддерживаемая поверхность интеграции.

---

# Tilda

Source: /ru/docs/embed/tilda.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

Tilda публикует статичный экспорт, поэтому загрузчик устанавливается через собственную функцию пользовательского кода Tilda. Приложения Make Agent Fast в каталоге Tilda нет. Названия меню указаны по состоянию на 2026-09; если пункт переехал, ищите настройку по её назначению, а не по точному пути.

## Добавьте загрузчик [#добавьте-загрузчик]

1. В панели Make Agent Fast включите **Встраивание** и добавьте в разрешённый список все origin, которые обслуживает Tilda — ваш домен и, на время тестирования, превью-адрес проекта `tilda.ws`.
2. Откройте настройки сайта проекта и найдите раздел пользовательского кода / внедрения HTML: поля, которые добавляют разметку в `<head>` каждой страницы или перед закрывающим тегом body. Доступность зависит от вашего тарифа Tilda.
3. Вставьте сгенерированный сниппет в поле head. Загрузчик работает с `async`, поэтому подходят и head, и конец body.
4. Сохраните и переопубликуйте страницы, где должен показываться загрузчик. Tilda отдаёт статичный экспорт, поэтому общий код доходит до посетителей только после повторной публикации.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Если вы не нашли эту настройку, вставьте сниппет в блок footer вашей темы: блок HTML-кода Tilda добавляет загрузчик только на страницу, где он размещён, — это также способ ограничить агента одной посадочной страницей.

## Проверьте [#проверьте]

1. Откройте опубликованный URL в приватном окне, а не в редакторе Tilda. Режимы редактирования и предпросмотра могут подавлять внедрённые скрипты.
2. Убедитесь, что origin в адресной строке совпадает с разрешённым, включая `www`, если домен на него перенаправляет.
3. Убедитесь, что `embed.js` возвращает `200` в панели Network и существует один элемент `data-maf-embed="YOUR_SITE_SLUG"`.
4. Задайте реальный вопрос и убедитесь, что сообщение появилось в разделе **Диалоги**.

## Решение проблем [#решение-проблем]

| Симптом                                              | Вероятная причина                                              | Решение                                                               |
| ---------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| Загрузчик виден в редакторе, но не на живой странице | Страницы не были переопубликованы после сохранения общего кода | Переопубликуйте каждую страницу, где нужен загрузчик                  |
| Загрузчик работает, но окно чата не открывается      | Живой origin не в разрешённом списке или встраивание выключено | Добавьте точный опубликованный origin и перепроверьте **Встраивание** |
| Сниппет появляется только на одной странице          | Он добавлен через HTML-блок уровня страницы                    | Перенесите его в поле внедрения в head на весь сайт                   |

Настройки cookie-согласия и скорости страницы Tilda могут откладывать сторонние скрипты. Если согласие включено, загружайте встраивание в категории, которую ему назначает ваша политика; разрешённые origin описаны в разделе [Безопасность и CSP](/ru/docs/embed/security).

---

# Vue и Nuxt

Source: /ru/docs/embed/vue-nuxt.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Подготовьте встраивание [#подготовьте-встраивание]

Включите встраивание для агента и добавьте точные origin локального, предпросмотра и продакшен-развёртываний. Решите, принадлежит ли агент всему приложению или только выбранным компонентам маршрутов.

## Плагин Nuxt на весь сайт [#плагин-nuxt-на-весь-сайт]

Создайте плагин `.client.ts`, чтобы никакой DOM-код не выполнялся при серверном рендеринге. Nuxt загружает его один раз в браузере, что сохраняет загрузчик и диалог стабильными между клиентскими переходами.

```ts
// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "Ask us";
  script.async = true;
  document.body.appendChild(script);
});
```

Не помещайте секреты в `runtimeConfig.public`; в браузере допустимы только публичный slug сайта и визуальные настройки. Настоящие ключи MAF API и провайдеров остаются в приватной серверной конфигурации.

У плагина на весь сайт намеренно нет очистки при размонтировании: он принадлежит времени жизни приложения Nuxt. При горячей замене модулей в разработке прежний корень может оставаться до полной перезагрузки; защита корня предотвращает второй загрузчик. Проверяйте финальное поведение на чистой продакшен-сборке, а не многократной правкой плагина в одной долгоживущей вкладке.

## Компонент Vue для отдельных маршрутов [#компонент-vue-для-отдельных-маршрутов]

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

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>
```

Используйте один компонент-владелец. Несколько компонентов с разными slug намеренно создают несколько агентов, что редко желательно.

Если приложение Vue переключает аутентифицированных арендаторов без полной загрузки страницы, трактуйте это как явное снятие/повторный монтаж. Удалите корень старого slug, проверьте публичный slug нового арендатора по доверенному состоянию приложения, затем добавьте новый скрипт. Изменение `script.dataset.agent` после выполнения загрузчика не перенацеливает существующий iframe.

Заголовки безопасности сайта по-прежнему действуют для вывода Nuxt/Vue. Добавьте origin загрузчика/фрейма в CSP и разрешайте микрофон только при включённом голосе; клиентский плагин не может переопределить политику браузера на уровне ответа.

## Проверьте SSR и маршрутизацию [#проверьте-ssr-и-маршрутизацию]

1. Запустите продакшен-сборку Nuxt/Vue и убедитесь, что нет ошибки `document is not defined`.
2. Загрузите маршрут со встраиванием напрямую и убедитесь, что корень один.
3. Переходите на клиенте и проверьте поведение на весь сайт против поведения по маршруту.
4. Проверьте `embed.js`, iframe, CSP и точный origin.
5. Отправьте сообщение и проверьте поведение на мобильном и с микрофоном.

## Решение проблем [#решение-проблем]

| Симптом                                   | Решение                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| Падение SSR                               | Переименуйте плагин Nuxt в `.client.ts` или держите DOM-работу в `onMounted` |
| Загрузчик остаётся после ухода с маршрута | Удаляйте корень с нужным slug в `onBeforeUnmount`                            |
| Загрузчик сбрасывается на каждом маршруте | Используйте клиентский плагин/макет на весь сайт вместо компонента страницы  |
| Превью-домен не работает                  | Добавьте этот точный HTTPS origin отдельно                                   |
| Скрипт вставляется дважды                 | Используйте одного стабильного владельца и защиту по корню/ID                |

Npm-адаптер для Vue/Nuxt пока не опубликован; этот гайд использует поддерживаемый размещённый загрузчик напрямую.

---

# Webflow

Source: /ru/docs/embed/webflow.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Доступность [#доступность]

Поддерживаемая интеграция — пользовательский код. Публичного приложения Make Agent Fast в Webflow Marketplace сегодня нет. Папка `integrations/webflow` в репозитории содержит тот же сниппет для подвала, что показан ниже, — а не нативное приложение Webflow.

## Пользовательский код [#пользовательский-код]

Добавьте сгенерированный скрипт в **Site settings → Custom code → Footer code** и опубликуйте.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Пользовательский код может не выполняться в предпросмотре Webflow Designer. Проверяйте опубликованные staging- и продакшен-домены и разрешайте каждый используемый origin.

---

# Wix

Source: /ru/docs/embed/wix.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Доступность пользовательского элемента [#доступность-пользовательского-элемента]

Используйте пользовательский элемент из `integrations/wix/make-agent-fast.js` или одобренную поверхность пользовательского кода в конце body от Wix. Этот исходник — не публичное приложение Wix App Market. URL листинга появится здесь только после того, как внешняя проверка одобрит и опубликует его.

## Пользовательский код [#пользовательский-код]

В настройках сайта добавьте сгенерированный загрузчик как пользовательский код в конец body и примените к нужным страницам.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wix может обслуживать предпросмотр и живой сайт на разных хостах. Добавляйте в разрешённый список встраивания только нужные хосты и переопубликуйте после изменений.

---

# WordPress

Source: /ru/docs/embed/wordpress.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: 'Обзор встраивания', icon: &#x22;embed&#x22; },
{ label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/ru/docs/embed/security&#x22;, label: 'Безопасность и CSP', icon: &#x22;shield&#x22; }
]"
/>

## Исходник плагина для ручной установки [#исходник-плагина-для-ручной-установки]

Исходник плагина для ручной установки находится в `integrations/wordpress/make-agent-fast`. Он не представлен в каталоге WordPress.org. Заархивируйте эту папку, загрузите через **Plugins → Add New → Upload Plugin**, затем укажите опубликованный slug в **Settings → Make Agent Fast**. Ссылка на каталог появится здесь только после одобрения внешней проверкой.

## Custom HTML [#custom-html]

При ручной установке добавьте стандартный скрипт через дочернюю тему, доверенный инструмент вставки в header/footer или блок Custom HTML, который разрешает ваш тариф WordPress.

```html
<script src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Добавьте в разрешённый список панели и продакшен-origin, и отдельный staging-origin. Очищайте кэш страниц и CDN после изменения сниппета.

<Callout title="Не правьте родительскую тему">
  Обновление родительской темы может перезаписать прямые правки. Для надёжной установки используйте плагин или дочернюю тему.
</Callout>

---

# Основные понятия

Source: /ru/docs/getting-started/concepts.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;site&#x22;, title: &#x22;Сайт&#x22;, description: &#x22;Единица рабочего пространства: агент, внешний вид, знания, встраивание и точки входа сообщений. Slug — это id встраивания.&#x22; },
{ icon: &#x22;chat&#x22;, title: &#x22;Агент&#x22;, description: &#x22;Идентичность, инструкции, языки и голосовая/текстовая личность, которую встречают посетители.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Знания&#x22;, description: &#x22;URL, файлы, заметки, FAQ и товары, на которых обоснованы ответы.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Каналы&#x22;, description: &#x22;Встраивания и коннекторы сообщений, доставляющие того же агента в другие места.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Кредиты&#x22;, description: &#x22;Учитываемые единицы для модели, голоса и использования платформы по вашему тарифу.&#x22; }
]"
/>

## Рабочее пространство [#рабочее-пространство]

Ваш аккаунт — граница рабочего пространства для сайтов, оплаты, учётных данных API и командных операций. Доступ к одному рабочему пространству никогда не даёт доступа к другому.

## Сайт [#сайт]

Сайт — единица рабочего пространства. Ему принадлежат агент, внешний вид, знания, коннекторы, аналитика и диалоги. Тариф может ограничивать число активных сайтов. Собственные домены не предлагаются. Публичный slug — это id встраивания (`data-agent`), а не настраиваемый домен.

## Агент [#агент]

Агент — диалоговое поведение, привязанное к сайту. Его характер и инструкции определяют, как он говорит; его знания определяют, на какие факты он может опираться в ответах.

## Знания [#знания]

Источники знаний — индексируемый материал: заметки, URL, файлы, FAQ и товары. Они поддерживают ответы, но не заменяют поведенческие инструкции. Обновляйте источник, когда факт меняется.

## Канал [#канал]

Канал — место, где посетитель говорит с агентом: встроенный виджет на вашем существующем сайте, оставшиеся размещённые демо-страницы, голос, Telegram, WhatsApp, Messenger, Instagram, Discord или KakaoTalk. Возможности различаются по каналам.

## Кредиты и права [#кредиты-и-права]

Операции ИИ расходуют кредиты. Минуты живого голоса, клонирование голоса, число сайтов и управление брендингом имеют отдельные права по тарифу. Запросы API, запускающие работу ИИ, используют те же базовые лимиты аккаунта.

## Состояние публикации [#состояние-публикации]

Запуск по URL создаёт неопубликованный черновик. **Показать на моём сайте** на экране **Разместите там, где ваши клиенты** (или на странице агента) включает встраивание на вашем существующем сайте; **Проверить мой сайт** подтверждает, что код действительно там. Новые агенты не получают размещённую маркетинговую страницу. Тесты владельца никогда не уходят в паблик.

**Активация** — первый диалог посетителя или первая собранная заявка, а не тест владельца.

Сохранение **внешнего вида** (и значка брендинга) обновляет живое встраивание без повторной публикации. Знания и характер по-прежнему следуют своим правилам сохранения. Поведение коннекторов и встраивания использует текущее опубликованное или настроенное состояние агента, как описано в гайде каждой функции.

---

# Обзор панели

Source: /ru/docs/getting-started/dashboard.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;layers&#x22;, title: &#x22;Главная рабочего пространства&#x22;, description: &#x22;Список сайтов, статус тарифа и точка входа для новых проектов.&#x22; },
{ icon: &#x22;build&#x22;, title: &#x22;Управление агентом&#x22;, description: &#x22;Квитанция запуска, агент, отображение и настройки установки одного агента.&#x22; },
{ icon: &#x22;chart&#x22;, title: &#x22;Инструменты операций&#x22;, description: &#x22;Входящие, аналитика, рассылки, монетизация и использование.&#x22; },
{ icon: &#x22;code&#x22;, title: &#x22;Настройки разработчика&#x22;, description: &#x22;Ключи API, вебхуки, OAuth-приложения и учётные данные интеграций.&#x22; }
]"
/>

Панель организована вокруг сайтов. Используйте переключатель сайтов перед изменением контента, учётных данных или операционных настроек. Вставленный URL сайта создаёт первый черновик на экране генерации, а не в этом домашнем списке — см. [Создание агента](/ru/docs/build/create-agent).

## Агент [#агент]

**Агент** открывается на квитанции запуска — что было проверено, где установлен, говорил ли с ним клиент, когда заканчивается пробный период — с живым виджетом рядом. Его вкладки покрывают идентичность и задачу агента, **Отображение** (вид виджета; сохранение обновляет живое встраивание), **Голос** и **Действия**. **Знания** содержат всё, на чём он отвечает. **Коннекторы** связывают каналы сообщений. Короткий список **Первых шагов** остаётся до первого диалога с клиентом.

## Сайт [#сайт]

**Встраивание** предоставляет установочный код и управление origin для существующего сайта. Функций «чат-сборка» или «генерация сайта» нет. Оставшиеся размещённые страницы, если есть, — не продукт создания.

## Активность [#активность]

**Диалоги** собирают ветки с сайта и коннекторов. **Аналитика** показывает трафик и вовлечённость. **Рассылки** отправляют утверждённые сообщения аудитории, а **Уведомления** — лента событий заявок, передач и бронирований в панели; она не настраивает внешние оповещения.

## Управление аккаунтом [#управление-аккаунтом]

**Использование** показывает кредиты и лимиты тарифа. Ключи API — учётные данные уровня аккаунта; создавайте их только для приложений, которым доверяете.

<Callout title="Проверьте активный сайт">
  Имя активного сайта показано в переключателе сайтов. Подтверждайте его перед удалением знаний, ротацией секретов коннекторов или публикацией.
</Callout>

---

# Быстрый старт

Source: /ru/docs/getting-started/quickstart.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/build/create-agent&#x22;, label: &#x22;Создать агента&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/ru/docs/build/knowledge&#x22;, label: &#x22;Добавить знания&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: &#x22;Встраивание&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/ru/docs/operate/conversations&#x22;, label: &#x22;Входящие&#x22;, icon: &#x22;message&#x22; }
]"
/>

Этот гайд ведёт вас от нового аккаунта до работающего агента на вашем собственном сайте. Писать код не нужно. Ваш 7-дневный пробный период начинается при регистрации — без карты и без выбора тарифа. URL, вставленный на главной странице, сохраняется через регистрацию. `/try` позволяет посетителям вставить URL и поговорить с черновиком с водяным знаком до его активации при регистрации.

## Прежде чем начать [#прежде-чем-начать]

Вам нужен аккаунт и публичный URL сайта, который будет представлять агент. Делайте первую версию узкой — один продукт или одна задача оценивается проще, чем агент, который должен отвечать на любой вопрос о компании.

## 1. Вставьте URL сайта [#1-вставьте-url-сайта]

На главной странице Make Agent Fast вставьте URL и продолжите. После регистрации или входа тот же URL сохраняется: вставлять его снова не придётся. На этом пути нет конструктора страниц.

Нет сайта? Первый экран также принимает несколько письменных ответов или образец, чтобы посмотреть, как это работает. Если у вас уже есть аккаунт, вставка URL всё равно начинает **новый** неопубликованный черновик с этого сайта.

## 2. Подождите, пока мы собираем черновик [#2-подождите-пока-мы-собираем-черновик]

Экран генерации показывает реальную работу:

1. **Чтение сайта**
2. **Сборка агента**
3. **Проверка ответов**

Обычно это занимает несколько секунд, а для большого сайта — до минуты. Пока идёт процесс, **Уже найдено** перечисляет прочитанное — название компании, контакты, часы работы, адрес, страницы. Если часы или адрес отсутствуют, их можно вписать прямо там. Ничего ещё не опубликовано.

## 3. Познакомьтесь с агентом [#3-познакомьтесь-с-агентом]

Вы попадаете на **Знакомство с агентом**: настоящий чат рядом с тремя быстрыми проверками — то, что он знает, то, что он не должен выдумывать, и запрос человека. Нажмите **Спросить**, прочитайте ответ и примите или исправьте его. Исправленный ответ становится знанием, которое агент использует дальше. Текстовая репетиция расходует кредиты. Запросы контакта и действия имитируются: ничего не отправляется, не бронируется и не засчитывается как клиент. Голосовые и заявочные процессы доступны после репетиции. Если вы меняете знания или поведение агента, повторите затронутые проверки.

Затем выберите, чем агент в основном должен заниматься и где клиенты вас находят. Каналы сообщений доступны на Operate; пробный Launch может один раз перейти на Operate с той же датой окончания.

## 4. Разместите там, где ваши клиенты [#4-разместите-там-где-ваши-клиенты]

Укажите, кто добавит его на ваш сайт, сохраните адрес страницы, где он будет работать, включите его и добавьте однострочный код (или отправьте его разработчику, или попросите установку с помощью). Затем нажмите **Проверить мой сайт** — мы ищем корректный установочный код на вашей странице и проверяем, что сайт разрешён. Затем откройте сайт и задайте виджету вопрос. Ручное подтверждение помечено отдельно; неудачная повторная проверка просит проверить снова. Копирование кода — не финиш; финиш — проверка. Новые агенты не получают размещённую маркетинговую страницу.

## 5. Активируйте реальным посетителем [#5-активируйте-реальным-посетителем]

Активация — это первый диалог **посетителя** или первая собранная заявка, а не тест владельца. Страница агента хранит квитанцию запуска и короткий список первых шагов, пока это не произойдёт. Полный цикл описан в [Создании агента](/ru/docs/build/create-agent).

## Следующие шаги [#следующие-шаги]

* [Настройте виджет](/ru/docs/build/appearance)
* [Встройте агента](/ru/docs/embed/overview)
* [Просматривайте диалоги и заявки](/ru/docs/operate/conversations)

---

# Аналитика

Source: /ru/docs/operate/analytics.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Трафик&#x22;, icon: &#x22;globe&#x22; },
{ label: &#x22;Вовлечённость&#x22;, icon: &#x22;chat&#x22; },
{ label: &#x22;Результаты&#x22;, icon: &#x22;chart&#x22; },
{ label: &#x22;Каналы&#x22;, icon: &#x22;connectors&#x22; }
]"
/>

## Определите окно измерения [#определите-окно-измерения]

Откройте страницу **Аналитика** сайта и выберите 7, 30, 90 дней или пользовательскую дату начала/конца. Выберите основную метрику, опциональный фильтр канала/источника и **Сравнить с предыдущим периодом**, когда нужна равноценная база.

Фильтры применяются к отчёту и URL, так что вид можно воспроизвести. Используйте эквивалентную длину кампании, будни, сезонность и состояние публикации при интерпретации сравнения. Большой процент от одного-двух событий — ненадёжное доказательство.

## Поймите основные метрики [#поймите-основные-метрики]

| Метрика       | Значение                                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Визиты**    | Записанные просмотры публичных страниц, дедуплицированные там, где модель аналитики может идентифицировать того же посетителя/день |
| **Диалоги**   | Начало диалога, а не каждый отдельный ход сообщения                                                                                |
| **Заявки**    | Собранные события/записи заявок в выбранном контексте                                                                              |
| **Конверсия** | Отношение визитов к заявкам; также изучайте визиты-к-диалогам и диалоги-к-заявкам                                                  |

Объём сообщений и среднее число сообщений на диалог — меры вовлечённости, а не дополнительные начала диалогов. Меры возвращающихся посетителей, без ответа, передач, бронирований и квалифицированных заявок описывают разные части пути.

## Читайте тренды, воронку и время [#читайте-тренды-воронку-и-время]

Используйте дневной тренд, чтобы найти точку изменения, затем сравните её с релизами, кампаниями, обновлениями источников, инцидентами провайдеров и изменениями публикации. Воронка разделяет три вопроса: начали ли посетители диалог, создали ли диалоги заявки и создали ли визиты заявки в целом?

Виды по часам и будням показывают, когда происходила записанная активность. Они полезны для расписания персонала и кампаний, но временные метки, география аудитории и малые выборки могут исказить простой вывод о «лучшем времени».

## Изучайте привлечение и каналы [#изучайте-привлечение-и-каналы]

Топ источников использует информацию referrer/UTM, когда доступна. Direct/none включает трафик, чей источник отсутствует или скрыт. Приватность браузера, приложения ссылок, редиректы, контроли согласия и кросс-устройственные пути делают атрибуцию неполной; не принуждайте неатрибутированные визиты в кампанию.

Производительность каналов сравнивает записанную текстовую, голосовую и реальную активность. Диалоги коннекторов сообщений вносят вклад в более широкую операционную картину, но не каждая внешняя платформа раскрывает ту же базу просмотров страниц или атрибуции, поэтому кросс-канальные конверсии не идеально эквивалентны.

## Находите пробелы знаний и диалогов [#находите-пробелы-знаний-и-диалогов]

Таблица вопросов показывает часто задаваемые темы и счётчики неразрешённых/пробелов. **На чём обосновывался ваш агент** показывает недавние ответы плюс записанные источники знаний. Используйте оба с реальной папкой **Диалоги**:

1. Найдите вопрос с высоким объёмом или высоким пробелом.
2. Прочитайте несколько полных веток.
3. Решите, является ли проблемой недостающее знание, конфликт, характер, язык, UI или намерение посетителя.
4. Сделайте одно контролируемое изменение.
5. Перепрогоните приёмочные тесты и сравните новый период.

Метрика указывает, куда исследовать; она не объясняет причину сама по себе.

## Управляйте заявками и продолжением [#управляйте-заявками-и-продолжением]

Область заявок показывает собранные заявки, поддерживает безопасные действия экспорта/удаления и может создавать проверенное продолжение. Отфильтрованная атрибуция заявок может использовать более новые события заявок, пока входящие заявок всё ещё показывают все собранные записи заявок; читайте примечание, показанное панелью, перед предположением, что счётчики должны точно совпадать.

## Экспортируйте отчёт [#экспортируйте-отчёт]

Используйте **Экспорт**, чтобы создать Markdown (`.md`), Excel (`.xlsx`) или вид печати/PDF для текущих фильтров. Опция PDF открывает оптимизированную для печати страницу; выберите **Сохранить как PDF** в браузере. Записывайте контекст фильтра/даты с экспортированным файлом и защищайте любые данные посетителей/заявок, которые он содержит.

Экспорты — снимки. Они не продолжают обновляться и не должны трактоваться как отдельный источник истины после изменения фильтров панели или нижележащих событий.

## Приватность и качество данных [#приватность-и-качество-данных]

Собирайте только аналитику, нужную для определённой цели, и отражайте релевантное отслеживание в раскрытиях посетителям. Блокировка согласия, контроли приватности, офлайн-доставка, подавление дубликатов, пробелы провайдеров и старые события могут давать неполные данные. Используйте временную метку последнего события панели, чтобы отличать «ноль» от «недавно не получаем события».

## Решение проблем [#решение-проблем]

| Симптом                                                    | Проверка                                                                                                    |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Отчёт пуст                                                 | Правильный сайт/дата/фильтр, опубликованный трафик, последнее событие, блокировка согласия и публичный тест |
| Счётчики визитов/диалогов отличаются от сообщений          | Ожидаемо; начала/просмотры дедуплицируются иначе, чем ходы сообщений                                        |
| Отфильтрованные заявки отличаются от общего числа входящих | Атрибуция отфильтрованных событий против всех хранимых записей заявок                                       |
| Источник direct/none                                       | Отсутствующий/скрытый referrer или UTM; воспроизведите с помеченной публичной ссылкой                       |
| Экспорт отличается от экрана                               | Те же фильтры/дата на момент экспорта и менялись ли живые данные после                                      |

---

# Рассылки

Source: /ru/docs/operate/broadcasts.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Получатели&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Шаблон&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Очередь&#x22;, icon: &#x22;bolt&#x22; }]" />

## Знайте текущий объём [#знайте-текущий-объём]

Функция рассылок в панели сейчас нацелена на **Kakao AlimTalk**. Это не общий редактор кампаний Telegram/WhatsApp/Messenger/Discord. Живой шлюз AlimTalk требует зарегистрированного профиля отправителя, утверждённого шаблона, настроенного провайдера платформы и доступного корейского номера телефона для каждого получателя.

Число получателей разрешается из нестёртых заявок на текущем сайте с достижимым контактным значением, дедуплицированных по контакту. Режим разработки/mock может принять запасной вариант по электронной почте, но реальный шлюз AlimTalk требует подходящий номер телефона. Подтвердите, что показанный режим живой, перед тем как считать поставленное в очередь сообщение реальной доставкой.

## Поймите границу отправки [#поймите-границу-отправки]

Выбор **Отправить** ставит в очередь одну долговечную задачу для каждого текущего подходящего получателя. Панель сейчас не предоставляет сегментацию по отправке, редактирование получателей, запланированное время, предпросмотр аудитории, паузу или отзыв. Не используйте кнопку, пока вся разрешённая аудитория не предназначена и не авторизована получить сообщение.

Форма принимает утверждённый код шаблона и тело до 2 000 символов. Провайдер может применять более короткий шаблон, точную утверждённую формулировку/переменные, время, профиль отправителя и лимиты политики. Постановка в очередь Make Agent Fast не переопределяет эти правила.

## Подготовьте соответствующую рассылку [#подготовьте-соответствующую-рассылку]

1. Подтвердите, что поток сбора заявок сайта запрашивал релевантный контакт и согласие/правовое основание.
2. Удалите или сотрите людей, с которыми не следует связываться, перед разрешением аудитории.
3. Подтвердите, что настроены живой провайдер AlimTalk и зарегистрированный ключ отправителя.
4. Получите утверждённый провайдером код шаблона и сопоставьте тело этому шаблону.
5. Проверьте идентичность отправителя, цель, ссылки, требуемые раскрытия и путь отказа.
6. Используйте отдельный тестовый сайт/аудиторию, если нужен небольшой продакшен-тест; текущий редактор нацелен на все подходящие заявки на своём сайте.

Не отправляйте учётные данные, чувствительные детали аккаунта, защищённые записи, выдуманную персонализацию или предложение, которое агент/сайт не утвердил.

## Ставьте в очередь и наблюдайте [#ставьте-в-очередь-и-наблюдайте]

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

«Отправлено» означает, что настроенный шлюз принял все отслеживаемые отправки. Это не доказывает доставку на телефон, прочтение, конверсию или действительное маркетинговое согласие. Используйте квитанции доставки шлюза и бизнес-отчётность, где доступны.

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

## Автоматизация API [#автоматизация-api]

Используйте `broadcasts:write`, чтобы создать черновик и поставить его в очередь через публичный API с доверенного сервера. Сохраняйте идемпотентность и проверяйте разрешение получателей/готовность провайдера. API не может сделать неутверждённый шаблон AlimTalk соответствующим.

## Решение проблем [#решение-проблем]

| Симптом                                        | Проверка                                                                                                          |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Кнопка отправки отключена                      | Нет подходящих заявок сайта с достижимым контактом                                                                |
| Режим показывает local/dev                     | Живой провайдер/учётные данные AlimTalk не настроены; реальной доставки клиентам нет                              |
| Шлюз отклоняет шаблон                          | Утверждённый код шаблона, тело/переменные, профиль отправителя и формат получателя                                |
| Число получателей включает непригодный контакт | Реальная доставка требует телефон; очистите сбор/данные заявок перед отправкой                                    |
| История остаётся в отправке                    | Ошибка очереди/провайдера и `число отправлено` против числа получателей                                           |
| Нужно связаться только с сегментом             | Сейчас не поддерживается в этом редакторе; создайте утверждённый отдельный процесс аудитории вместо отправки всем |

Прекращайте отправку при появлении жалоб, неожиданных получателей, несовпадения шаблона или ошибок провайдера.

---

# Диалоги и заявки

Source: /ru/docs/operate/conversations.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Объединённые ветки&#x22;, description: &#x22;Истории веба, голоса, реального времени и коннекторов появляются в одной папке входящих только для чтения.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Обоснование&#x22;, description: &#x22;Сообщения ассистента показывают сохранённые цитаты источников, когда они доступны.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;Заявки&#x22;, description: &#x22;Собранные имена, электронные адреса и намерения поддерживают осознанное продолжение.&#x22; }
]"
/>

## Читайте объединённые входящие [#читайте-объединённые-входящие]

Откройте страницу **Диалоги** сайта, чтобы увидеть новейшие 30 веток по размещённому/встроенному веб-чату, голосовым сообщениям, транскриптам живых звонков, Telegram, WhatsApp, Messenger, Instagram, Discord и KakaoTalk. Используйте **Загрузить ещё**, чтобы идти назад по времени последней активности.

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

Входящие — поверхность проверки владельца, а не редактор ответов канала. Продолжайте через утверждённый путь контакта вместо предположения, что на каждый внешний коннектор можно ответить из панели.

## Поймите границы идентичности [#поймите-границы-идентичности]

Веб, живой голос и каждый коннектор используют разные идентификаторы посетителей. Пользователь Telegram, посетитель браузера и номер WhatsApp — отдельные идентичности, если у вас нет явных согласованных данных связывания. Похожие отображаемые имена не доказывают, что две ветки принадлежат одному человеку.

Метки коннекторов могут идентифицировать бота/Страницу/приложение вместо посетителя, когда внешняя платформа не предоставляет безопасную отображаемую идентичность. Относитесь к ID каналов и выведенным именам как к недоверенным метаданным, а не авторизации.

## Проверяйте качество ответов [#проверяйте-качество-ответов]

Для репрезентативной ветки:

1. Читайте вопрос посетителя в контексте вместо оценки только последнего ответа.
2. Подтвердите, что ответ следует границам характера/языка.
3. Изучите показанные источники обоснования и сравните их с текущей версией знаний.
4. Отметьте неотвеченные, повторяющиеся, вводящие в заблуждение или ненужные уточняющие вопросы.
5. Добавьте проверенный недостающий факт в знания/FAQ и протестируйте его в новом диалоге.

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

## Собирайте и управляйте заявками [#собирайте-и-управляйте-заявками]

Сбор заявок может хранить имя посетителя, электронный адрес и заявленный запрос, когда поток агента это позволяет. Недавние заявки появляются в **Аналитике**, где владелец может сгенерировать/отправить утверждённое продолжение, экспортировать данные заявок или удалить отдельную заявку.

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

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

## Экспортируйте и удаляйте безопасно [#экспортируйте-и-удаляйте-безопасно]

Экспорт заявок создаёт нижестоящую копию под вашим контролем. Храните её только в утверждённых системах, ограничивайте доступ и включайте в процедуры хранения/удаления. Удаление заявки убирает эту запись заявки, но может не стереть связанный диалог, сообщение провайдера, предыдущий экспорт, уведомление или юридически удерживаемую запись оплаты.

Отключение встраивания или коннектора тоже не стирает автоматически его исторические ветки. Следуйте процессу приватности аккаунта, когда посетитель делает запрос на удаление/доступ, и удаляйте нижестоящие копии тоже.

## Регламент операционной проверки [#регламент-операционной-проверки]

* Ежедневно во время запуска: проверяйте новые ветки, передачи, сбои провайдеров и ответы высокого риска.
* Еженедельно: группируйте повторяющиеся вопросы, выявляйте пробелы знаний и проверяйте статус продолжения заявок.
* После изменений контента/модели: перепрогоняйте приёмочный набор и проверяйте цитаты.
* После инцидента: сохраняйте безопасные временные метки/ID, изолируйте затронутый канал и избегайте распространения сырых приватных транскриптов.

## Решение проблем [#решение-проблем]

| Симптом                                  | Проверка                                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Ожидаемая ветка отсутствует              | Правильный сайт, доставка канала, последнее событие коннектора, завершение публичного теста и время активности              |
| Ветка открывается с меньшим числом ходов | Был ли источник живым транскриптом, историей коннектора или другой идентичностью посетителя/канала                          |
| Цитата отсутствует                       | Ответ мог не использовать извлекаемые знания, или старые записи могут не иметь метаданных цитат                             |
| Один человек появляется дважды           | Ожидаемо для отдельных идентификаторов браузера/канала; не объединяйте только по имени                                      |
| Продолжение недоступно                   | Электронный адрес/контакт заявки, состояние доступа, конфигурация отправки, лимиты частоты и требования проверки владельцем |

---

# Монетизация

Source: /ru/docs/operate/monetization.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Предложения&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Оплата&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Заказы&#x22;, icon: &#x22;chart&#x22; }]" />

## Поймите два отношения оплаты [#поймите-два-отношения-оплаты]

**Монетизация** позволяет владельцу сайта продавать предложение посетителю. Это отдельно от тарифа Make Agent Fast владельца и пакетов кредитов. Записи выручки/заказов создателя и использование платформы владельцем должны сверяться отдельно.

Страница показывает текущий режим оплаты. &#x2A;*Polar (живые платежи)** может принимать настроенные реальные покупки. &#x2A;*Local/dev (тестовый режим)** для поведения разработки и никогда не должен представляться как урегулированный продакшен-платёж.

## Создайте предложение [#создайте-предложение]

Выберите один из поддерживаемых видов:

| Тип                             | Предполагаемое использование                               |
| ------------------------------- | ---------------------------------------------------------- |
| **Платный доступ**              | Разблокировать опыт агента только для участников           |
| **Платный звонок/консультация** | Продать консультацию или результат звонка                  |
| **Чаевые**                      | Поддержка с фиксированной ценой или «плати сколько хочешь» |
| **Цифровой товар**              | Продать определённый цифровой результат/доступ             |

Введите конкретное название, описание, цену в центах, валюту и опциональный ключ продукта Polar. Ключ сопоставляет предложение с настроенным продуктом провайдера. Активное предложение может показываться или рекомендоваться в диалоге агента; неактивное остаётся видимым владельцу, но не должно продаваться.

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

## Закройте агента за платный доступ [#закройте-агента-за-платный-доступ]

Сначала создайте и активируйте предложение **Платный доступ**, затем выберите его в **Агент только для участников**. Посетители, не разблокировавшие его, получают путь покупки/разблокировки вместо обычного доступа к чату. Только активные продукты доступа можно выбрать; среда выполнения также отказывает открыто, а не навсегда ломает чат, если выбранное предложение исчезает.

Протестируйте поведение неавторизованного/нового посетителя, успешной оплаты, возврата доступа, отменённой оплаты, дублирующего события провайдера, неактивного предложения и возврата/отзыва перед запуском.

## Настройте механизмы оплаты [#настройте-механизмы-оплаты]

Для живой оплаты Polar развёртывание платформы и сопоставление продукта должны быть настроены. Опциональный контроль корейских платежей может предлагать KakaoPay/Naver Pay/Toss для предложений KRW только когда платформа сообщает об этом механизме как доступном; включение недоступного переключателя не создаёт интеграцию провайдера.

Используйте тестовый режим провайдера, где поддерживается, затем проверьте небольшую реальную покупку по вашей операционной политике. Подтвердите минимальные единицы валюты: для USD `2500` означает `$25.00`. Не угадывайте поведение центов для валюты с другими соглашениями минимальных единиц.

## Просматривайте заказы и выручку [#просматривайте-заказы-и-выручку]

Страница сообщает число оплаченных заказов, сводку выручки и недавние покупки. «Оплачено» отражает записанное состояние оплаты/провайдера; сверяйте комиссии провайдера, налоги, возвраты, чарджбэки, выплаты и выполнение в соответствующей финансовой системе.

Удаление предложения не стирает исторические записи заказов или оплаты. Деактивация безопаснее удаления, когда оператору нужна существующая конфигурация для расследования.

## Опциональное ценообразование за результат [#опциональное-ценообразование-за-результат]

**Оплата за результат** может списывать фиксированную сумму кредитов кошелька владельца за заявку, квалифицированную агентом, или запрос бронирования, который человек позже подтверждает, в дополнение к обычному использованию. Это не оплата посетителем и не становится выручкой создателя. Квалификация агентом — не принятие продажи человеком, а запрос бронирования — не подтверждённая встреча. Оставляйте этот режим выключенным, если владелец не понимает дополнительное списание кредитов и точные определения событий.

## Чек-лист запуска [#чек-лист-запуска]

* Режим живой/тестовой оплаты безошибочно понятен.
* Название предложения, описание, валюта, цена и продукт провайдера совпадают.
* Выполнение, длительность доступа, возвраты, налог, поддержка и приватность задокументированы.
* Знания агента содержат только утверждённые коммерческие утверждения.
* Пути успеха, отмены, дубликата, возврата и неактивного предложения протестированы.
* Оповещения о покупках, владелец выполнения, бухгалтерская сверка и процесс инцидентов назначены.

## Решение проблем [#решение-проблем]

| Симптом                                         | Проверка                                                                                       |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Предложение не появляется                       | Оно активно, релевантно диалогу и состояние сайта актуально                                    |
| Живая оплата недоступна                         | Конфигурация платежей развёртывания и ключ продукта провайдера предложения                     |
| Доступ остаётся заблокированным после оплаты    | Записанное состояние покупки, правильный посетитель/сессия, вебхук провайдера и ID предложения |
| Переключатель корейских платежей не действует   | Механизм платформы не настроен/недоступен или валюта предложения не поддерживается             |
| Выручка отличается от выплаты                   | Комиссии провайдера, возвраты, чарджбэки, налоги, время расчёта и валюта                       |
| Кредиты владельца уменьшаются после результатов | Включено опциональное ценообразование за результат в дополнение к обычному использованию       |

---

# Уведомления

Source: /ru/docs/operate/notifications.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Заявка&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Передача&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Бронирование&#x22;, icon: &#x22;bolt&#x22; }]" />

## Что появляется здесь [#что-появляется-здесь]

Страница **Уведомления** сайта — лента событий в панели. Она сейчас записывает три типа событий для владельца:

| Тип              | Значение                                          |
| ---------------- | ------------------------------------------------- |
| **Заявка**       | Агент собрал запись контакта/намерения посетителя |
| **Передача**     | Диалог запросил или вызвал продолжение человеком  |
| **Бронирование** | Записан результат бронирования                    |

Каждый элемент может показывать тип события, время создания, имя/электронный адрес посетителя, когда доступны, и короткий отрывок. Непрочитанный элемент визуально выделен и вносит вклад в счётчик непрочитанных.

Эта страница — не экран настроек уведомлений или внешней доставки. Отметка элемента прочитанным не отправляет письмо посетителю, не отвечает коннектору, не меняет заявку и не отписывает никого от внешнего провайдера.

## Проверяйте и отмечайте события [#проверяйте-и-отмечайте-события]

1. Откройте **Уведомления** для нужного сайта.
2. Приоритизируйте передачи и чувствительные ко времени бронирования.
3. Откройте связанный контекст **Диалогов** или **Аналитики**, когда идентичность и намерение нуждаются в подтверждении.
4. Выбирайте **Отметить прочитанным** только после того, как ответственный владелец его рассмотрел.
5. Используйте **Отметить все прочитанными** только когда каждое видимое/непрочитанное событие было намеренно проверено.
6. Выбирайте **Загрузить ещё** для более старых страниц.

Состояние прочтения — помощник процесса владельца, а не доказательство, что посетитель получил продолжение. Отслеживайте реальное продолжение в утверждённой системе записи.

## Защищайте данные посетителей [#защищайте-данные-посетителей]

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

Удаление или отметка уведомления не удаляет автоматически связанную заявку, диалог, бронирование, запись провайдера или экспортированную копию. Используйте процесс приватности/удаления для запросов субъектов данных.

## Решение проблем [#решение-проблем]

| Симптом                                        | Проверка                                                                                                   |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Ожидаемое событие отсутствует                  | Правильный сайт, реальное завершение заявки/передачи/бронирования, время события и связанный диалог        |
| Счётчик непрочитанных кажется устаревшим       | Обновите после действия отметки и убедитесь, что оно сообщило об успехе                                    |
| Отметка прочитанным не связалась с посетителем | Ожидаемо; эта лента не отправляет продолжений                                                              |
| Старый элемент отсутствует                     | Используйте **Загрузить ещё**; первая страница намеренно ограничена                                        |
| Нужны настройки email/Slack                    | Не настраиваются с этой страницы; используйте доступный внешний процесс/API/вебхуки платформы вместо этого |

Для автоматизации потребляйте поддерживаемые ресурсы публичного API или подписанные события вебхуков вместо скрейпинга этой панели.

---

# Кредиты и использование

Source: /ru/docs/operate/usage.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Кредиты&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Минуты голоса&#x22;, icon: &#x22;voice&#x22; }, { label: &#x22;Пополнения&#x22;, icon: &#x22;bolt&#x22; }]" />

## Читайте страницу использования [#читайте-страницу-использования]

Область использования панели объединяет контекст оплаты с ресурсами, которые могут остановить операцию: текущий тариф, баланс кредитов, лимит сайтов, минуты живого голоса, право клона, варианты пополнения и действия оплаты. Проверяйте её перед запуском и после добавления высокообъёмного встраивания, коннектора или клиента API.

Не интерпретируйте одно число как универсальную квоту. Каждое право защищает отдельный ресурс.

## Различайте балансы и лимиты [#различайте-балансы-и-лимиты]

| Ресурс                 | Сбрасывается или истекает                               | Что происходит на лимите                                                               |
| ---------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Ежемесячные кредиты ИИ | Переносятся на один дополнительный цикл, затем истекают | Учитываемые действия ИИ/знаний/голоса могут отклоняться                                |
| Купленные кредиты      | Не истекают при активной подписке                       | Продолжают финансировать учитываемую работу, пока доступ активен                       |
| Число сайтов           | Право тарифа                                            | Создание ещё одного сайта заблокировано                                                |
| Минуты живого голоса   | Ежемесячный лимит тарифа                                | Новые или продолжающиеся сессии реального времени ограничены/завершаются               |
| Клоны голоса           | Число тарифа/право честного использования               | Ещё одно первое клонирование заблокировано; замена существующего клона сайта разрешена |
| Запросы API            | На ключ API в минуту                                    | Запрос возвращает `429` с заголовками повтора                                          |

Кредиты не покупают дополнительную пропускную способность API, сайты, живые минуты или клоны. Право не гарантирует путь кредитов/провайдера, требуемый для завершения операции.

## Что расходует кредиты [#что-расходует-кредиты]

Учитываемая работа может включать генерацию сайта/агента, обычные ответы агента, эмбеддинги знаний, транскрибацию медиа, синтез речи, голос коннекторов и клонирование голоса. Стоимость меняется с провайдером, моделью, длиной промпта/контекста, длиной вывода, длительностью аудио и типом операции. Одно «сообщение» поэтому не имеет фиксированной универсальной цены в кредитах.

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

## Читайте историю использования [#читайте-историю-использования]

**История использования** показывает финальные кредиты, фактически потреблённые каждой завершённой операцией. Временные авторизационные удержания, расчёты резервов и возвраты остаются внутренними деталями учёта вместо появления как отдельные клиентские строки. Очень малые операции эмбеддинга показываются как `<0.001` вместо округления до нуля.

**Другие изменения баланса** — отдельная таблица для грантов кредитов тарифа, пополнений, истечений и ручных корректировок. Она не дублирует обычное использование ИИ. Пока операция ещё выполняется, расходуемый баланс может временно отражать удержание перед появлением финальной строки использования или освобождением неудачной операции; обновляйте после завершения при сверке только что законченного действия.

## Ежемесячные и купленные кредиты [#ежемесячные-и-купленные-кредиты]

Ежемесячный лимит идёт от активного тарифа. Неиспользованные ежемесячные кредиты переносятся на один дополнительный цикл, затем истекают. Разовые пакеты добавляют 1 000 кредитов за $8, 5 000 за $35 или 15 000 за $90; купленные кредиты не истекают при активной подписке.

Покупка пакета не восстанавливает отменённую/истёкшую подписку платформы. Сначала решите проблему доступа/оплаты, когда панель сообщает о проблеме прав, а не только о низком балансе.

## Автопополнение [#автопополнение]

Автопополнение покупает пакет кредитов за вас, когда баланс падает до выбранного порога. Включите его в **Настройки → Использование → Автопополнение**: выберите порог (от 50 до 5 000 кредитов) и пакет для покупки. Оно списывает карту, уже сохранённую у провайдера платежей; добавьте или измените эту карту через ссылку клиентского портала рядом с формой.

Защиты намеренны. Только одна покупка выполняется за раз, и пока она рассчитывается, страница сообщает, что покупка в процессе. Максимум три автоматические покупки происходят в день. Кредиты появляются при расчёте платежа, а не при начале списания. Если карта отклонена, кредиты не добавляются, страница показывает последнюю ошибку, и одно письмо в тот день объясняет, что исправить; списание не повторяется, пока способ оплаты не заработает.

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

## Дополнения [#дополнения]

Дополнения добавляют ёмкость поверх текущего тарифа. Они оплачиваются ежемесячно, могут быть отменены в любое время и управляются в **Настройки → Использование → Дополнения**.

| Дополнение           | Цена                  | Примечания                                                                   |
| -------------------- | --------------------- | ---------------------------------------------------------------------------- |
| Дополнительный агент | $10 за агента в месяц | Покупайте больше одного; каждый добавляет один слот агента. Включён в Scale. |
| Убрать значок        | $9 в месяц            | Скрывает «Made with Make Agent Fast» на виджете. Включено в Operate и Scale. |

Дополнение — отдельная подписка от тарифа, поэтому отмена дополнения не трогает тариф, а отмена тарифа не сохраняет тихо дополнение. Отменённое дополнение работает до конца уже оплаченного периода. Только владелец оплаты может купить или отменить его.

## Учёт живого голоса [#учёт-живого-голоса]

Operate включает 30 живых минут в месяц, Scale — 90. Каждый звонок также имеет настроенный владельцем автоматический лимит длительности от 30 секунд до 20 минут. Когда выдаётся токен живого звонка, кошелёк списывается заранее за максимальную серверно-авторизованную длительность, ограниченную оставшимся месячным лимитом. Та же длительность удерживается против лимита живых минут, так что параллельные звонки не могут его превысить.

Живое медиа течёт напрямую между браузером и провайдером реального времени, поэтому сервер не может независимо проверить более короткую клиентскую длительность. Неиспользованное время поэтому не возвращается частично после выдачи токена; брошенная или неотчитанная сессия списывается по авторизованному лимиту. Серверный сбой до выдачи токена освобождает списание. Завершайте звонки чисто, чтобы закрыть сессию быстро, но прогнозируйте кредиты по настроенному лимиту звонка, а не ожидаемому времени разговора звонящего.

Голосовые сообщения другие: они расходуют учитываемую работу транскрибации/модели/речи вместо права живых минут. Диагностируйте правильную корзину, когда один режим работает, а другой нет.

## Прогнозируйте использование [#прогнозируйте-использование]

1. Выберите репрезентативные короткие, обычные и длинные вопросы посетителей.
2. Тестируйте текст, ответы с большими знаниями, голосовые сообщения и живые звонки отдельно.
3. Записывайте изменения кредитов/минут для приёмочного набора.
4. Умножайте на ожидаемый дневной трафик и микс каналов.
5. Добавляйте запас на повторы, сканирования, сбои провайдеров, внутренний QA, кампании и всплески трафика.
6. Перепроверяйте после изменения модели, провайдера, размера источника, длины ответа или поведения голоса.

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

## Предотвращайте неожиданное использование [#предотвращайте-неожиданное-использование]

* Ограничивайте встраивания точными предназначенными origin.
* Давайте ключам API минимальные области и разделяйте ключи по сервису/окружению.
* Делайте мутации идемпотентными и соблюдайте заголовки повтора `429`.
* Проверяйте подписи вебхуков и дедуплицируйте ID событий.
* Немедленно ротируйте утёкшие учётные данные API/провайдера/коннектора.
* Держите публичных агентов ограниченными ясным характером и инструкциями ответов.
* Удаляйте устаревшую автоматизацию, предпросмотры развёртываний, коннекторы и неиспользуемые ключи.
* Оповещайте операционных владельцев до того, как балансы или живые минуты приблизятся к нулю.

## Исследуйте всплеск [#исследуйте-всплеск]

Записывайте затронутое рабочее пространство/сайт, диапазон времени, канал, развёртывание и недавние изменения. Сравнивайте использование с аналитикой, временными метками диалогов, ID запросов API, логами доставки вебхуков и состоянием последнего события/ошибки коннектора. Не отправляйте ключи в открытом виде или содержимое посетителей в поддержку, если утверждённый безопасный процесс явно этого не требует.

Сначала изолируйте источник: отключите коннектор, отзовите ключ, удалите непредназначенный origin или остановите цикл повторов клиента. Затем сохраните безопасные доказательства, ротируйте учётные данные где нужно и повторно включайте один путь за раз.

## Решение проблем [#решение-проблем]

| Симптом                                              | Проверка                                                                                                 |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Нет кредитов при неиспользованных живых минутах      | Отдельные ресурсы; добавьте/продлите кредиты для обычной работы ИИ                                       |
| Голосовые сообщения работают, живой звонок нет       | Право тарифа на живое, оставшиеся минуты, ключ реального времени и состояние сессии                      |
| Пополнение куплено, но функция всё ещё заблокирована | Пакеты добавляют только кредиты; проверьте право тарифа/сайта/клона/домена                               |
| API возвращает `429` при оставшихся кредитах         | Частота запросов на ключ; следуйте заголовкам сброса/повтора                                             |
| Домен сообщает о требовании оплаты                   | Восстановите Operate/Scale, затем активируйте снова, если панель это предлагает                          |
| Баланс неожиданно падает                             | Недавние встраивания, коннекторы, ключи API, индексация, голос/клонирование и повторы провайдера/клиента |

См. [Тарифы и цены](/ru/docs/account/pricing) для текущей таблицы прав.

---

# Собственные домены

Source: /ru/docs/publish/custom-domains.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: &#x22;Обзор встраивания&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/ru/docs/embed/html&#x22;, label: &#x22;HTML-сниппет&#x22;, icon: &#x22;code&#x22; }
]"
/>

Make Agent Fast **не** продаёт, привязывает, проверяет или настраивает домены клиентов. Нет панели для подключения `yourname.com`, покупки домена или настройки `slug.makeagent.fast` как публичного адреса сайта.

Разместите агента на сайте, который у вас уже есть, с `embed.js` и `data-agent="<slug>"`. Slug — это id встраивания. Это не домен, который вы настраиваете.

Оставшиеся события дополнения собственных доменов Polar игнорируются или отменяются и никогда не начисляют кредиты.

См. [Обзор встраивания](/ru/docs/embed/overview) и [HTML и JavaScript](/ru/docs/embed/html).

---

# Размещённые сайты

Source: /ru/docs/publish/hosted-sites.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ru/docs/build/appearance&#x22;, label: &#x22;Внешний вид&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/ru/docs/embed/overview&#x22;, label: &#x22;Встраивание&#x22;, icon: &#x22;embed&#x22; }
]"
/>

Размещённые маркетинговые страницы — **наследие**. Уже опубликованные сайты арендаторов (включая публичные демо `demo` и `demo-business`) по-прежнему открываются на `https://YOUR_SLUG.makeagent.fast`. &#x2A;*Новые агенты не получают размещённую маркетинговую страницу.** Утверждение включает встраивание на существующем сайте клиента. См. [Обзор встраивания](/ru/docs/embed/overview).

Собственные домены не предлагаются. Slug — это id встраивания (`data-agent`), а не домен, который вы настраиваете.

## Slug по-прежнему id встраивания [#slug-по-прежнему-id-встраивания]

Используйте короткое имя, которое вы узнаёте. Валидный slug не должен сталкиваться с другим арендатором или зарезервированным маршрутом платформы вроде `docs`, `dashboard` или `api`. Относитесь к нему как к публичной информации. Его изменение после запуска может сломать встраивания.

## Оставшиеся размещённые страницы [#оставшиеся-размещённые-страницы]

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

**Внешний вид** (и значок брендинга): **Сохранить внешний вид** обновляет живое встраивание (и любую оставшуюся размещённую страницу) без повторной публикации. См. [Внешний вид](/ru/docs/build/appearance).

## Подключите другие поверхности [#подключите-другие-поверхности]

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

Для Notion, Linktree, подписей электронной почты, QR-кодов и других поверхностей, которые не могут загружать произвольный JavaScript, ссылайтесь на страницу **на вашем собственном сайте** со встраиванием — а не на поддомен Make Agent Fast (если у вас нет оставшегося размещённого демо).

## Отмена публикации [#отмена-публикации]

Отмена публикации отключает публичную оставшуюся размещённую страницу и переключатель встраивания; она не удаляет сайт, источники знаний, агентов, историю диалогов или конфигурацию внешних провайдеров. Подключённые боты сообщений могут продолжать отвечать; отключайте/удаляйте каждый коннектор отдельно.

## Решение проблем [#решение-проблем]

| Симптом                                                   | Проверка                                                                                                                                  |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Публичный оставшийся URL возвращает недоступно/не найдено | Ожидаемо для новых агентов (нет размещённой страницы). Для оставшихся сайтов: точный slug, состояние публикации, активный доступ аккаунта |
| Изменение в панели отсутствует                            | Правильный сайт, результат сохранённого действия, тест **встраивания** в приватном окне                                                   |
| Коннектор отвечает при выключенном встраивании            | Ожидаемо; отключите коннектор отдельно, если весь доступ по каналам должен прекратиться                                                   |