接入与配置

本指南将指导您创建 Agent 并定义其配置。接入操作仅用于准备 Agent 资源，并不会使其自动回复每位客户。

接入电话号码

请求体为可选参数。仅当 Agent 需要使用特定 Meta 目录时，才包含 catalog_id。 API 参考： POST Onboard Agent · GET Get Settings

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 '{}'

保留返回的标识符：

{
  "agent_id": "AGENT_ID"
}

接入操作会调度后台准备工作。当前的 YCloud REST 接口未提供单独的接入状态端点。请求成功响应后，请使用 GET Get Settings 确认电话作用域的资源是否已就绪。如果读取临时失败，请稍作延迟后重试；切勿盲目重复接入操作。返回 403 通常表示产品访问权限或条款接受未完成。后续电话作用域操作中返回 404 可能表示 Phone Number ID 不正确，或者同一个 YCloud 租户名下未拥有活跃的 Public API Agent 绑定。

配置人工转接与跟进行为

在测试人工转接工作流之前，请先在 Agent 配置中定义这些消息和时间间隔。 API 参考： GET Get Settings · PUT Replace Settings

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`	Agent 是否可以将对话转接至人工工作流。
`handoff.message_selection`	转接消息来源：`DEFAULT`、`AGENT` 或 `CUSTOM`。
`handoff.message`	触发转接时发送给客户的消息。
`followup.enabled`	Agent 是否在无互动后发送跟进消息。
`followup.followup_interval_in_seconds`	发送跟进消息前的延迟时间。
`followup.message`	发送给客户的跟进消息。
`never_say_phrases`	Agent 禁止使用的完整短语列表。

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

字段	含义
`payment_method`	客户需要了解的支付方式及条件。
`return_policy`	退货、退款或换货政策。
`purchase_info`	客户购买、预订或下单的方式。
`delivery_and_shipping`	配送范围、方式、费用和时效。
`business_description`	关于企业及其产品/服务的通俗说明。
`contact_info.email`	面向客户的联系邮箱。
`contact_info.hours_of_operation`	人类可读的营业或支持时间。
`contact_info.address`	面向客户的商家地址。

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."
  }'

业务信息对象是封闭的。请仅发送 YCloud API Schema 中定义的字段。

添加常见问题 (FAQ)

每个 FAQ 仅对应一个客户意图。请更新或删除过时的答案，而不是添加高度重复的条目。 API 参考： GET List FAQs · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE Delete FAQ

字段	必填	含义
`question`	是	用自然语言表述的客户问题。
`answer`	是	Agent 应使用的准确答案。
`metadata`	否	与 FAQ 一同保留的字符串键值对元数据。
`id`	仅响应	用于获取、更新或删除 FAQ 的标识符。
`created_at`	仅响应	创建时间戳。

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."
  }'

使用关联的集合端点列出或创建常见问题解答，并使用关联的单项端点检索、更新或删除单个常见问题解答。

添加网站和文件

仅在网站和文件的内容为最新且适合用于回答客户时使用它们。 网站 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} 检索、更新或删除它。网站响应可以包含 crawl_status、pages_crawled、last_crawled_at 和 created_at。抓取是异步进行的，因此成功的创建响应并不意味着每个页面都已被索引。将文件作为 multipart/form-data 上传，并包含一个名为 file 的部分：

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} 检索或删除单个文件。

PDF 或 CSV 文件中的表格可能无法被可靠解析。请将文件作为检索来源并测试代表性内容。不要假设智能体可以将源图片或文件发送回给客户。

添加行为技能

技能说明智能体应如何处理任务。知识说明什么是事实。 API 参考： GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skill

字段	限制	含义
`agent_id`	可选	需要显式选择时的智能体 ID。
`title`	64 个字符	小写字母、数字和连字符，前后不得包含连字符。
`description`	1,024 个字符	何时应使用该技能。
`skill`	20,000 个字符	完整的行为指令。
`id`	仅响应	用于检索、更新或删除该技能的标识符。

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 和字符串元数据。为每个技能设定一个目标。说明何时使用它，将强制性规则放在示例之前，并定义在信息缺失时该如何处理。将易变的事实保留在业务信息、常见问题解答、网站或文件中。

添加 UI 技能

UI 技能控制智能体可以呈现哪些富媒体 WhatsApp 组件。行为技能定义智能体应如何处理任务。 API 参考： GET List UI Skills · POST Create UI Skill · GET Get UI Skill · PATCH Update UI Skill · DELETE Delete UI Skill

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 技能的显示标题。
`component_type`	智能体可以呈现的富媒体 WhatsApp 组件。
`status`	`enabled` 或 `disabled`。
`instruction`	智能体何时应使用此组件。
`flow_id`	WhatsApp Flow ID。仅当 `component_type` 为 `flow` 时为必填项；对于所有其他类型请省略。

支持的组件类型包括 carousel_quick_reply、carousel_url、cta_url、flow、image、interactive_list、interactive_reply_buttons、location 和 location_request。更新端点仅更改 title、status 和 instruction。如果需要不同的组件类型或 Flow 关联，请创建新的 UI 技能。列表请求支持 before、after 和 limit。只要存在 paging.next，就继续进行分页。响应时间戳为 Unix 纪元秒。

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

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

配置连接器

Connector 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`	对 Agent 配置可见的连接器名称。
`description`	外部服务的用途和边界。
`base_url`	HTTP 基础 URL 或远程 MCP 服务器地址。
`connector_protocol`	可选的 `HTTP` 或 `MCP`；创建时省略则默认为 HTTP。协议在创建后无法更改。
`auth_type`	身份验证策略。
`auth_config`	OAuth 客户端凭据或 API 密钥配置。
`user_auth_injection_config`	用户凭据注入的位置和方式。
`requires_certificate`	连接器是否需要 mTLS 凭据。
`connection_status`	返回的连接器验证状态和可选错误。
`mtls_config`	返回的证书是否存在及元数据。
`mcp_tool_sync`	可选的可空发现元数据：`status=ERROR`、`PENDING` 或 `READY`、Unix 秒级尝试/成功时间戳、`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 客户端凭据需要 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 连接器，使用 Connector API 返回的 Meta Connector ID 调用 /connectors/{connectorId}/refreshMCPTools，以请求 Meta 重新发现其工具。请勿发送请求体。HTTP 200 会返回当前连接器，但这并不总是意味着发现成功。请检查 mcp_tool_sync.status：READY 表示发现已完成，PENDING 表示仍在进行中，ERROR 表示远程发现或配置失败。该操作没有幂等性密钥。请勿自动重试；超时后，请重新获取连接器，因为刷新结果是不确定的。

定义工具

Tool API 参考： GET List Connector Tools · POST Create Connector Tool · GET Get Connector Tool · PATCH Update Connector Tool · DELETE Delete Connector Tool

字段	含义
`name`	Agent 使用的工具名称。
`description`	用于工具选择的触发条件和预期结果。
`request_definition.method`	`GET`、`POST`、`PUT`、`DELETE` 或 `PATCH`。
`request_definition.path`	相对于 `base_url` 的路径。
`request_definition.path_parameters`	命名路径参数定义。
`request_definition.query_parameters`	命名查询参数定义。
`request_definition.headers`	命名请求头定义。
`request_definition.body`	JSON 请求体字段和必填字段列表。
`user_auth_required`	操作是否需要最终用户凭据。
`transformation_spec`	可选的可空有序响应转换。更新时省略可保留该转换，发送 `null` 可将其删除，或发送一个对象进行设置。
`user_auth_action_config`	如何从身份验证操作中读取令牌、刷新令牌和过期值。

在 /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 表示不进行转换。更新时，这三种输入存在差异：

{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false}

省略该字段将保留当前的转换。如需删除它：

{"name":"get_order","description":"Gets an order","request_definition":{"method":"GET","path":"/orders"},"user_auth_required":false,"transformation_spec":null}

如需设置它：

{"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 需要重新发现连接器的工具时，请使用上述刷新操作。

下一步：测试和评估

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

开始使用

指南

接口

Webhooks

接入电话号码

配置人工转接与跟进行为

配置业务信息

添加常见问题 (FAQ)

添加网站和文件

添加行为技能

添加 UI 技能

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

配置连接器

定义工具

转换工具响应

检查 MCP 发现状态

下一步：测试和评估

​接入电话号码

​配置人工转接与跟进行为

​配置业务信息

​添加常见问题 (FAQ)

​添加网站和文件

​添加行为技能

​添加 UI 技能

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

​配置连接器

​定义工具

​转换工具响应

​检查 MCP 发现状态

下一步：测试和评估

接入电话号码

配置人工转接与跟进行为

配置业务信息

添加常见问题 (FAQ)

添加网站和文件

添加行为技能

添加 UI 技能

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

配置连接器

定义工具

转换工具响应

检查 MCP 发现状态