跳转到主要内容
本指南将指导您创建智能体并定义其配置。入驻旨在准备智能体资源,并不会让智能体自动回复每位客户。

入驻电话号码

请求体为可选参数。仅在智能体需要使用特定 Meta 目录时,才包含 catalog_id。 API 参考: POST Onboard Agent · GET Get Settings
请保留返回的标识符:
入驻操作会在后台安排准备工作。目前的 YCloud REST 接口未提供单独的入驻状态端点。收到成功响应后,请使用 GET Get Settings 确认电话作用域的资源是否已就绪。如果读取暂时失败,请在稍作延迟后重试读取;请勿盲目重复执行入驻操作。 返回 403 通常意味着产品访问权限未开通或条款接受尚未完成。在后续执行电话作用域操作时若返回 404,则可能表示电话号码 ID 不正确,或者同一个 YCloud 租户未拥有处于活动状态的 Public API 智能体绑定。

将测试消费者添加到允许名单

调用 POST /v2/metaBusinessAgents/{entityId}/allowListEntries 时,仅可提供一个非空的身份标识:
或者,以 E.164 格式提供 consumer_phone_number。公开 API 会直接使用您指定的身份;它不会根据电话号码反查 BSUID。电话号码与 BSUID 条目具有独立的 ID,且各自占用 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
业务信息对象是封闭结构。请仅发送 YCloud API 规范中已定义的字段。

添加常见问题解答(FAQ)

每个 FAQ 请保持对应单一的客户意图。应直接更新或删除过时的答案,避免添加近似重复的内容。 API 参考: GET List FAQs · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE Delete FAQ
使用链接的集合端点列出或创建常见问题,使用链接的单项端点检索、更新或删除单个常见问题。 对于 PATCH,请同时发送 question 和 answer。Meta 可能会返回新的 id 并将 created_at 重置为更新时间。后续请求请使用返回的 ID。超时或 502 并不证明更新失败;请勿自动重试更新或创建替代的常见问题。

添加网站和文件

仅在网站和文件的内容为最新且适合用于回答客户时,才使用它们。 网站 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 文件中的表格可能无法被可靠地解析。请将文件作为检索来源并测试具有代表性的内容。不要假定 Agent 能够将源图片或源文件发回给客户。

添加行为技能

技能阐述 Agent 应如何处理任务。知识则阐述什么是真实的。 API 参考: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skill
使用链接的集合端点列出或创建技能,使用链接的单项端点检索、更新或删除单个技能。响应还可以包含 channel、created_at 和字符串元数据。 为每项技能设定一个目标。说明何时使用它,将强制性规则置于示例之前,并明确在信息缺失时该如何处理。将易变的事实保留在业务信息、常见问题、网站或文件中。

添加 UI Skills

UI Skills 控制 Agent 可以展示哪些丰富的 WhatsApp 组件。行为技能则定义 Agent 应如何处理任务。 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。如果您需要不同的组件类型或 Flow 关联,请创建一个新的 UI Skill。列表请求支持 before、after 和 limit。当存在 paging.next 时继续分页。响应时间戳为 Unix 纪元秒。

仅在需要时添加连接器和工具

连接器定义了一个外部 HTTP 服务或远程 MCP 服务器。工具定义了 agent 可以在该连接器上调用的一个操作。当静态知识已足够时,请勿添加任何一种资源。

配置连接器

连接器 API 参考: GET 获取连接器列表 · POST 创建连接器 · GET 获取连接器 · PATCH 更新连接器 · POST 刷新 MCP 连接器工具 · DELETE 删除连接器 凭证 API 参考: PUT 更新或插入 API 密钥 · PUT 更新或插入 OAuth 凭证 · PUT 更新或插入证书 创建和更新请求都需要 name、description、base_url 和 auth_type。标准身份验证类型为 OAUTH2_CLIENT_CREDENTIALS、API_KEY 和 NONE。Meta 可能会拒绝未为该账户启用的其他契约值。 对于 API 密钥身份验证,请将值注入到 headers、query_params 或 body_params 中。每一项都需要非空的 field_name 和 value;prefix 为可选项。必须至少存在一项。 OAuth 客户端凭证需要 token_url、scopes_to_request、client_id 和 client_secret。提供时,token_request_content_type 必须为 application/x-www-form-urlencoded 或 application/json。对于 mTLS,请在 client_certificate 和 client_key 中提供 PEM 文本;ca_certificate 为可选项。切勿记录凭据请求体日志。 使用 /connectors 列出或创建连接器。使用 /connectors/{connectorId} 获取、更新或删除单个连接器。通过其 /credentials/apiKey、/credentials/oauth 或 /credentials/certificate 子资源替换凭证。 对于 MCP 连接器,请使用连接器 API 返回的 Meta 连接器 ID 调用 /connectors/{connectorId}/refreshMCPTools,以请求 Meta 重新发现其工具。无需发送请求体。HTTP 200 会返回当前连接器,但这并不总是意味着发现成功。请检查 mcp_tool_sync.status:READY 表示发现已完成,PENDING 表示仍在进行中,ERROR 表示远程发现或配置失败。该操作没有幂等键。请勿自动重试;发生超时后,请获取连接器信息,因为刷新结果是不确定的。

定义工具

工具 API 参考: GET 获取连接器工具列表 · POST 创建连接器工具 · GET 获取连接器工具 · PATCH 更新连接器工具 · DELETE 删除连接器工具 在 /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 需要重新发现连接器的工具时,请使用上述刷新操作。

下一步:测试与评估

验证响应和具有代表性的业务场景。