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

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

Тело запроса является необязательным. Указывайте catalog_id только тогда, когда агент должен использовать определенный каталог Meta. Справочник по API: POST Onboard Agent · GET Get Settings
Сохраните возвращенный идентификатор:
Подключение запускает фоновую подготовку. В текущем REST API YCloud нет отдельного эндпоинта для проверки статуса подключения. После успешного ответа используйте GET Get Settings, чтобы убедиться, что ресурсы на уровне номера телефона готовы. Если запрос на чтение временно завершается сбоем, повторите его через некоторое время; не повторяйте процедуру подключения вслепую. Ошибка 403 обычно означает, что доступ к продукту или принятие условий не завершены. Ошибка 404 при последующих операциях на уровне номера телефона может означать, что Phone Number ID неверен или что у текущего тенанта YCloud нет активной привязки агента Public API.

Добавление тестового клиента в список разрешенных

Используйте POST /v2/metaBusinessAgents/{entityId}/allowListEntries ровно с одним ненулевым идентификатором:
Либо укажите consumer_phone_number в формате E.164. Публичный API использует указанный вами идентификатор; он не ищет BSUID по номеру телефона. Записи номеров телефонов и BSUID имеют независимые идентификаторы и каждая занимает один из 20 общих слотов WhatsApp. Удаление выполняется по ID выбранной записи. Ответы со списком требуют только id; идентификатор может быть недоступен. consumer_instagram_username принимается только как необязательное поле ответа, а не как возможность управления Instagram.

Настройка перевода диалога и повторных сообщений

Определите эти сообщения и интервалы времени в рамках конфигурации агента перед тестированием процесса перевода диалога. Справочник по API: GET Get Settings · PUT Replace Settings
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 · PUT Replace Business Info · DELETE Delete Business Info
Объект информации о компании является закрытым. Передавайте только те поля, которые определены схемой API YCloud.

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

Привязывайте один интент клиента к одному вопросу FAQ. Обновляйте или удаляйте устаревшие ответы вместо добавления похожих дубликатов. Справочник по API: GET List FAQs · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE Delete FAQ
Используйте указанные эндпоинты для коллекций, чтобы получать список или создавать FAQ, и эндпоинты для отдельных элементов, чтобы получать, обновлять или удалять конкретный FAQ. Для PATCH передавайте одновременно question и answer. Meta может вернуть новый id и сбросить created_at на время обновления. Используйте возвращённый ID для последующих запросов. Таймаут или 502 не доказывают сбой обновления; не повторяйте его автоматически и не создавайте дублирующий FAQ.

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

Используйте сайты и файлы только в том случае, если их контент актуален и подходит для ответов клиентам. Справочник по API сайтов: GET List Websites · POST Create Website · GET Get Website · PATCH Update Website · DELETE Delete Website Справочник по API файлов: GET List Files · POST Upload File · GET Get File · DELETE Delete File Создайте источник веб-сайта с помощью его url. Используйте /websites/{websiteId} для его получения, обновления или удаления. Запросы принимают поля области действия included_sub_domains, included_url_patterns, excluded_sub_domains, excluded_url_patterns и single_urls. Опустите поле области действия, чтобы оставить его незаданным; отправьте [], чтобы очистить его. Ответы могут содержать все пять массивов области действия: crawl_error, crawl_status, pages_crawled, last_crawled_at и created_at. Обновление может вернуть другой id; используйте возвращённый ID для последующих операций чтения, обновления и удаления. Не повторяйте автоматически обновление с неопределённым результатом. Сканирование выполняется асинхронно, поэтому успешный ответ на создание не означает, что каждая страница уже проиндексирована. Загрузите файл как multipart/form-data с одной частью с именем file:
YCloud требует непустое исходное имя файла и принимает файлы в запросах размером до 100 000 000 байт. Meta определяет окончательное принятие типов файлов и контента. Список файлов доступен по адресу /files; получить или удалить конкретный файл можно по адресу /files/{fileId}.
Таблицы в файлах PDF или CSV могут интерпретироваться ненадежно. Рассматривайте файлы как источники для поиска информации и тестируйте характерный контент. Не предполагайте, что агент сможет отправить исходное изображение или файл обратно клиенту.

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

Навыки объясняют, как агент должен выполнять задачу. База знаний объясняет, что является фактом. Справочник по API: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skill
Используйте указанные эндпоинты коллекций для вывода списка или создания навыков, а связанные эндпоинты элементов — для получения, обновления или удаления отдельного навыка. Ответы также могут содержать channel, created_at и строковые метаданные. Задавайте каждому навыку одну цель. Указывайте, когда его использовать, размещайте обязательные правила перед примерами и определяйте, что делать при отсутствии информации. Изменяемые факты храните в информации о компании, FAQ, сайтах или файлах.

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

UI Skills определяют, какие расширенные компоненты WhatsApp может отображать агент. Поведенческие навыки определяют, как агент должен выполнять задачу. Справочник по API: GET List UI Skills · POST Create UI Skill · GET Get UI Skill · PATCH Update UI Skill · DELETE Delete UI Skill
Поддерживаемые типы компонентов: 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 · POST Create Connector · GET Get Connector · PATCH Update Connector · POST Refresh MCP Connector Tools · DELETE Delete Connector Справочник по API учетных данных: PUT Upsert API Key · PUT Upsert OAuth Credentials · PUT Upsert Certificate 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 · POST Create Connector Tool · GET Get Connector Tool · PATCH Update Connector Tool · DELETE Delete Connector Tool Создавайте и получайте список инструментов по адресу /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 без пересылки вышестоящему сервису.

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

Не равное null поле 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 означает отсутствие преобразования. При обновлении эти три варианта различаются:
Если поле опущено, текущее преобразование сохраняется. Чтобы удалить его:
Чтобы задать его:
Макросы привязки поддерживают 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 необходимо заново обнаружить инструменты коннектора.

Далее: Тестирование и оценка

Проверяйте ответы и типовые бизнес-сценарии.