Подключение номера телефона
Тело запроса является необязательным. Указывайтеcatalog_id только тогда, когда агент должен использовать определенный каталог Meta.
Справочник по API: POST Onboard Agent · 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 Settingsfollowup_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Добавление часто задаваемых вопросов
Привязывайте один интент клиента к одному вопросу FAQ. Обновляйте или удаляйте устаревшие ответы вместо добавления похожих дубликатов. Справочник по API: GET List FAQs · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE Delete FAQPATCH передавайте одновременно 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:
/files; получить или удалить конкретный файл можно по адресу /files/{fileId}.
Добавление поведенческих навыков
Навыки объясняют, как агент должен выполнять задачу. База знаний объясняет, что является фактом. Справочник по API: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skillchannel, 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 Certificatename, 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 необходимо заново обнаружить инструменты коннектора.
Далее: Тестирование и оценка
Проверяйте ответы и типовые бизнес-сценарии.

