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

# Подключение и настройка

> Создайте Meta Business Agent и настройте его параметры, знания, навыки, коннекторы и инструменты.

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

## Подключение номера телефона

Тело запроса является необязательным. Включайте `catalog_id` только в том случае, если агент должен использовать определенный каталог Meta.

**Справочник API:** [POST Onboard Agent](/api-reference/meta-business-agents/onboard-agent) · [GET Get Settings](/api-reference/meta-business-agents/get-settings)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/onboarding" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

Сохраните возвращенный идентификатор:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "agent_id": "AGENT_ID"
}
```

Подключение запускает фоновую подготовку. В текущем REST API YCloud нет отдельного эндпоинта для проверки статуса подключения. После успешного ответа используйте [GET Get Settings](/api-reference/meta-business-agents/get-settings), чтобы убедиться в готовности ресурсов на уровне номера телефона. Если чтение временно завершается сбоем, повторите попытку через небольшую паузу; не повторяйте процедуру подключения вслепую.

Ошибка `403` обычно означает, что доступ к продукту или принятие условий не завершены. Ошибка `404` при последующих операциях на уровне номера телефона может означать, что Phone Number ID неверен или что у этого тенанта YCloud нет активной привязки агента Public API.

## Настройка передачи оператору и последующих сообщений

Задайте эти сообщения и временные интервалы в рамках конфигурации агента до тестирования сценария передачи диалога человеку.

**Справочник API:** [GET Get Settings](/api-reference/meta-business-agents/get-settings) · [PUT Replace Settings](/api-reference/meta-business-agents/replace-settings)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "handoff": {
      "enabled": true,
      "message_selection": "CUSTOM",
      "message": "I am connecting you with a support specialist."
    },
    "followup": {
      "enabled": true,
      "followup_interval_in_seconds": 3600,
      "message": "Do you still need help?"
    },
    "never_say_phrases": ["I guarantee delivery by tomorrow"]
  }'
```

| Поле | Описание |
| - | - |
| `handoff.enabled` | Может ли агент передавать диалог человеку. |
| `handoff.message_selection` | Источник сообщения о передаче: `DEFAULT`, `AGENT` или `CUSTOM`. |
| `handoff.message` | Сообщение для клиента, отправляемое при запуске передачи диалога. |
| `followup.enabled` | Отправляет ли агент напоминание после периода неактивности. |
| `followup.followup_interval_in_seconds` | Задержка перед отправкой напоминания. |
| `followup.message` | Текст напоминания для клиента. |
| `never_say_phrases` | Полный список фраз, которые агенту запрещено произносить. |

Значением `followup_interval_in_seconds` должно быть одно из следующих: `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800` или `86400`. Если `handoff.message_selection` имеет значение `CUSTOM`, укажите `handoff.message`.

YCloud обновляет только те параметры, которые переданы в запросе. Опустите `never_say_phrases`, чтобы сохранить текущий список. Отправьте пустой массив для его очистки или непустой массив для полной замены списка.

## Настройка информации о компании

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

**Справочник API:** [GET Get Business Info](/api-reference/meta-business-agents/get-business-info) · [PUT Replace Business Info](/api-reference/meta-business-agents/replace-business-info) · [DELETE Delete Business Info](/api-reference/meta-business-agents/delete-business-info)

| Поле | Описание |
| - | - |
| `payment_method` | Способы и условия оплаты, о которых следует знать клиентам. |
| `return_policy` | Правила возврата, возмещения средств или обмена. |
| `purchase_info` | Как клиенты могут совершить покупку, забронировать или оформить заказ. |
| `delivery_and_shipping` | Зоны, способы, стоимость и сроки доставки. |
| `business_description` | Понятное описание компании и ее предложений. |
| `contact_info.email` | Контактный адрес электронной почты для клиентов. |
| `contact_info.hours_of_operation` | График работы или часы поддержки в понятном формате. |
| `contact_info.address` | Фактический адрес компании для клиентов. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/businessInfo" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "business_description": "Example Store sells home and office products.",
    "return_policy": "Unused items can be returned within 30 days.",
    "delivery_and_shipping": "Standard delivery takes 3 to 5 business days."
  }'
```

Объект информации о компании является закрытым. Передавайте только те поля, которые определены в схеме API YCloud.

## Добавление часто задаваемых вопросов

Закрепляйте за каждым вопросом FAQ только одно намерение клиента. Обновляйте или удаляйте устаревшие ответы вместо добавления похожих дубликатов.

**Справочник API:** [GET List FAQs](/api-reference/meta-business-agents/list-faqs) · [POST Create FAQ](/api-reference/meta-business-agents/create-faq) · [GET Get FAQ](/api-reference/meta-business-agents/get-faq) · [PATCH Update FAQ](/api-reference/meta-business-agents/update-faq) · [DELETE Delete FAQ](/api-reference/meta-business-agents/delete-faq)

| Поле | Обязательно | Описание |
| - | - | - |
| `question` | Да | Вопрос клиента на естественном языке. |
| `answer` | Да | Фактический ответ, который должен использовать агент. |
| `metadata` | Нет | Метаданные типа «строка-строка», сохраняемые вместе с вопросом. |
| `id` | Только в ответе | Идентификатор для получения, обновления или удаления вопроса. |
| `created_at` | Только в ответе | Временная метка создания. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/faqs" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "question": "How can I return an item?",
    "answer": "Contact support with your order number within 30 days of delivery."
  }'
```

Используйте связанные эндпоинты коллекции для получения списка или создания FAQ, а связанные эндпоинты элементов — для получения, обновления или удаления отдельного FAQ.

## Добавление веб-сайтов и файлов

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

**Справочник по API веб-сайтов:** [GET List Websites](/api-reference/meta-business-agents/list-websites) · [POST Create Website](/api-reference/meta-business-agents/create-website) · [GET Get Website](/api-reference/meta-business-agents/get-website) · [PATCH Update Website](/api-reference/meta-business-agents/update-website) · [DELETE Delete Website](/api-reference/meta-business-agents/delete-website)

**Справочник по API файлов:** [GET List Files](/api-reference/meta-business-agents/list-files) · [POST Upload File](/api-reference/meta-business-agents/upload-file) · [GET Get File](/api-reference/meta-business-agents/get-file) · [DELETE Delete File](/api-reference/meta-business-agents/delete-file)

Создайте источник веб-сайта с его `url`. Используйте `/websites/{websiteId}`, чтобы получить, обновить или удалить его. Ответы по веб-сайту могут включать `crawl_status`, `pages_crawled`, `last_crawled_at` и `created_at`. Сканирование выполняется асинхронно, поэтому успешный ответ на создание не означает, что каждая страница уже проиндексирована.

Загрузите файл в виде `multipart/form-data` с одной частью с именем `file`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/files" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "file=@./returns-policy.pdf"
```

YCloud требует непустое исходное имя файла и принимает файлы запроса размером до 100 000 000 байт. Meta контролирует окончательное принятие типа файла и его содержимого. Получить список файлов можно по адресу `/files`; получить или удалить отдельный файл — по адресу `/files/{fileId}`.

<Warning>
  Таблицы в файлах PDF или CSV могут интерпретироваться ненадежно. Рассматривайте файлы как источники для извлечения информации и тестируйте репрезентативное содержимое. Не предполагайте, что агент сможет отправить исходное изображение или файл обратно клиенту.
</Warning>

## Добавление поведенческих навыков

Навыки объясняют, как агент должен решать задачу. База знаний объясняет, какие факты верны.

**Справочник по API:** [GET List Skills](/api-reference/meta-business-agents/list-skills) · [POST Create Skill](/api-reference/meta-business-agents/create-skill) · [GET Get Skill](/api-reference/meta-business-agents/get-skill) · [PATCH Update Skill](/api-reference/meta-business-agents/update-skill) · [DELETE Delete Skill](/api-reference/meta-business-agents/delete-skill)

| Поле | Ограничение | Значение |
| - | - | - |
| `agent_id` | Необязательно | Идентификатор агента, когда требуется явный выбор. |
| `title` | 64 символа | Строчные буквы, цифры и дефисы, без дефиса в начале или в конце. |
| `description` | 1 024 символа | Когда следует использовать навык. |
| `skill` | 20 000 символов | Полные поведенческие инструкции. |
| `id` | Только в ответе | Идентификатор, используемый для получения, обновления или удаления навыка. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/skills" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "return-request",
    "description": "Collect the information needed to start a return.",
    "skill": "Ask for the order number. Explain the return policy. If the item is outside the policy, offer human handoff."
  }'
```

Используйте связанные эндпоинты коллекции для получения списка или создания навыков, а связанные эндпоинты элементов — для получения, обновления или удаления отдельного навыка. Ответы также могут включать `channel`, `created_at` и строковые метаданные.

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

## Добавление навыков интерфейса (UI Skills)

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

**Справочник по API:** [GET List UI Skills](/api-reference/meta-business-agents/list-ui-skills) · [POST Create UI Skill](/api-reference/meta-business-agents/create-ui-skill) · [GET Get UI Skill](/api-reference/meta-business-agents/get-ui-skill) · [PATCH Update UI Skill](/api-reference/meta-business-agents/update-ui-skill) · [DELETE Delete UI Skill](/api-reference/meta-business-agents/delete-ui-skill)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/uiSkills" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Choose a support topic",
    "component_type": "interactive_reply_buttons",
    "status": "enabled",
    "instruction": "Use these reply buttons when the customer asks for support but has not selected a topic."
  }'
```

| Поле | Значение |
| - | - |
| `title` | Отображаемое название навыка интерфейса (UI Skill). |
| `component_type` | Интерактивный компонент WhatsApp, который агент может отображать. |
| `status` | `enabled` или `disabled`. |
| `instruction` | Когда агент должен использовать этот компонент. |
| `flow_id` | Идентификатор WhatsApp Flow. Обязателен только тогда, когда `component_type` имеет значение `flow`; для всех остальных типов опускайте его. |

Поддерживаемые типы компонентов: `carousel_quick_reply`, `carousel_url`, `cta_url`, `flow`, `image`, `interactive_list`, `interactive_reply_buttons`, `location` и `location_request`.

Эндпоинт обновления изменяет только `title`, `status` и `instruction`. Создайте новый UI Skill, если вам требуется другой тип компонента или привязка к Flow. Запросы на получение списка поддерживают `before`, `after` и `limit`. Продолжайте постраничную навигацию, пока присутствует `paging.next`. Метки времени в ответе указаны в секундах эпохи Unix.

## Добавление коннекторов и инструментов только при необходимости

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

### Настройка коннектора

**Справочник по API коннекторов:** [GET List Connectors](/api-reference/meta-business-agents/list-connectors) · [POST Create Connector](/api-reference/meta-business-agents/create-connector) · [GET Get Connector](/api-reference/meta-business-agents/get-connector) · [PATCH Update Connector](/api-reference/meta-business-agents/update-connector) · [POST Refresh MCP Connector Tools](/api-reference/meta-business-agents/refresh-mcp-connector-tools) · [DELETE Delete Connector](/api-reference/meta-business-agents/delete-connector)

**Справочник по API учетных данных:** [PUT Upsert API Key](/api-reference/meta-business-agents/upsert-connector-api-key) · [PUT Upsert OAuth Credentials](/api-reference/meta-business-agents/upsert-connector-o-auth) · [PUT Upsert Certificate](/api-reference/meta-business-agents/upsert-connector-certificate)

| Поле | Описание |
| - | - |
| `name` | Название коннектора, отображаемое в конфигурации агента. |
| `description` | Назначение и границы внешнего сервиса. |
| `base_url` | Базовый URL HTTP или адрес удаленного MCP-сервера. |
| `connector_protocol` | Необязательное значение `HTTP` или `MCP`; если не указано при создании, по умолчанию используется HTTP. Протокол нельзя изменить после создания. |
| `auth_type` | Стратегия аутентификации. |
| `auth_config` | Конфигурация OAuth client-credentials или API-ключа. |
| `user_auth_injection_config` | Где и как передаются учетные данные пользователя. |
| `requires_certificate` | Ожидает ли коннектор учетные данные mTLS. |
| `connection_status` | Возвращаемый статус валидации коннектора и возможная ошибка. |
| `mtls_config` | Возвращаемые данные о наличии сертификата и метаданные. |
| `mcp_tool_sync` | Необязательные метаданные обнаружения (могут быть null): `status=ERROR`, `PENDING` или `READY`, временные метки попытки/успеха в формате Unix seconds, `fingerprint` и `tool_count`. |

`name`, `description`, `base_url` и `auth_type` обязательны для запросов на создание и обновление. Стандартные типы аутентификации: `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY` и `NONE`. Meta может отклонить другое значение схемы, если оно не включено для аккаунта.

Для аутентификации по API-ключу передавайте значения в `headers`, `query_params` или `body_params`. Каждый элемент требует непустых `field_name` и `value`; поле `prefix` необязательно. Должен присутствовать хотя бы один элемент.

Для OAuth client credentials требуются `token_url`, `scopes_to_request`, `client_id` и `client_secret`. При указании поле `token_request_content_type` должно иметь значение `application/x-www-form-urlencoded` или `application/json`. Для mTLS предоставьте PEM-текст в `client_certificate` и `client_key`; поле `ca_certificate` необязательно. Никогда не логируйте тела запросов с учетными данными.

Используйте `/connectors` для получения списка или создания коннекторов. Используйте `/connectors/{connectorId}` для получения, обновления или удаления коннектора. Заменяйте учетные данные через его подресурсы `/credentials/apiKey`, `/credentials/oauth` или `/credentials/certificate`.

Для MCP-коннектора вызовите `/connectors/{connectorId}/refreshMCPTools` с идентификатором Meta Connector ID, возвращенным Connector API, чтобы запросить у Meta повторное обнаружение инструментов. Не передавайте тело запроса. Ответ HTTP `200` возвращает текущий коннектор, но это не всегда означает успешное завершение обнаружения. Проверьте `mcp_tool_sync.status`: `READY` означает, что обнаружение завершено, `PENDING` — что оно еще выполняется, а `ERROR` — что удаленное обнаружение или подготовка завершились сбоем. У операции нет ключа идемпотентности. Не повторяйте ее автоматически; при таймауте запросите коннектор повторно, так как результат обновления не определен.

### Определение инструментов

**Справочник по API инструментов:** [GET List Connector Tools](/api-reference/meta-business-agents/list-connector-tools) · [POST Create Connector Tool](/api-reference/meta-business-agents/create-connector-tool) · [GET Get Connector Tool](/api-reference/meta-business-agents/get-connector-tool) · [PATCH Update Connector Tool](/api-reference/meta-business-agents/update-connector-tool) · [DELETE Delete Connector Tool](/api-reference/meta-business-agents/delete-connector-tool)

| Поле | Описание |
| - | - |
| `name` | Название инструмента, используемое агентом. |
| `description` | Триггер и ожидаемый результат, используемые для выбора инструмента. |
| `request_definition.method` | `GET`, `POST`, `PUT`, `DELETE` или `PATCH`. |
| `request_definition.path` | Путь относительно `base_url`. |
| `request_definition.path_parameters` | Определения именованных параметров пути. |
| `request_definition.query_parameters` | Определения именованных query-параметров. |
| `request_definition.headers` | Определения именованных заголовков запроса. |
| `request_definition.body` | Поля тела JSON и список обязательных полей. |
| `user_auth_required` | Требуются ли для операции учетные данные конечного пользователя. |
| `transformation_spec` | Необязательное упорядоченное преобразование ответа (может быть null). Опустите при обновлении, чтобы сохранить его, отправьте `null`, чтобы удалить, или отправьте объект, чтобы задать. |
| `user_auth_action_config` | Как считывать значения токена, refresh-токена и срока действия из действия аутентификации. |

Создавайте и просматривайте список инструментов с помощью `/connectors/{connectorId}/tools`. Получайте, обновляйте или удаляйте инструмент с помощью `/tools/{toolId}`.

Определения параметров включают `type` данных, понятное человеку `description`, флаг обязательности и необязательный `binding`. Привязка может предоставлять фиксированное значение, макрос или входные данные среды выполнения.

Запросы на создание и обновление требуют `name`, `description`, `request_definition` и `user_auth_required`. Определение запроса требует `method` и `path`. Тело требует `content_type=application/json` и объект `params`. При указании `user_auth_action_config` требует `user_action_tool_type` (`auth` или `refresh`) и `user_auth_token_path`; `expires_at_type` должно быть `absolute` или `relative_seconds`. Недопустимые определения коннекторов или инструментов возвращают HTTP `400` без перенаправления на вышестоящий уровень.

### Преобразование ответов инструментов

Ненулевой `transformation_spec` требует наличия `version=1` и `steps`, содержащих не более пяти упорядоченных шагов.
Каждый шаг требует `kind`. Необязательные поля `target` и `params` принимают строки или `null`; `params` содержит
JSON-объект, закодированный в виде строки. Выражение `math` поддерживает не более четырех уровней вложенности.

Поддерживаемые типы: `allowlist`, `case`, `catalog`, `decorate_url`, `dedupe`, `dehydrate`, `filter`,
`first_nonempty`, `first_nonnull`, `first_nonzero`, `format`, `html_escape`, `lookup`, `math`,
`proxy_image`, `reshape`, `shadow_allowlist`, `string_replace` и `truncate`.

При создании пропуск или `null` означает отсутствие преобразования. При обновлении эти три варианта различаются:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":null}
```

Чтобы установить его:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":{"version":1,"steps":[{"kind":"allowlist","params":"{\"paths\":[\"order.id\",\"order.status\"]}"}]}}
```

Макросы привязки поддерживают `WHATSAPP_PHONE_NUMBER`, `WHATSAPP_PHONE_NUMBER_NATIONAL`,
`WHATSAPP_IDENTITY_HASH`, `WHATSAPP_CURRENT_STATUS_ID`, `WHATSAPP_BSUID`, `USER_MESSAGE`,
`WHATSAPP_CONVERSATION_ID`, `WHATSAPP_MESSAGE_ID`, `INSTAGRAM_IGSID` и
`INSTAGRAM_CONVERSATION_ID`. Принятие макроса Instagram не включает сущности Instagram
и не гарантирует его значение для пользователя WhatsApp.

### Проверка состояния обнаружения MCP

MCP использует ту же конечную точку и поля аутентификации. Успешный ответ коннектора может содержать
`mcp_tool_sync.status=ERROR`; это означает сбой обнаружения инструментов. Создание коннектора не
означает, что инструменты готовы к работе. Время первого обнаружения и специфические ограничения на редактирование MCP
еще не были проверены. Используйте операцию обновления выше, когда Meta требуется повторно обнаружить инструменты коннектора.

<Card title="Далее: Тестирование и оценка" icon="arrow-right" href="/ru/documentation/meta-business-agent/test-and-evaluate">
  Проверьте ответы и типовые бизнес-сценарии.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.