> ## 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 并配置其设置、知识库、技能、连接器和工具。

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

## 接入电话号码

请求体为可选参数。仅当 Agent 需要使用特定 Meta 目录时，才包含 `catalog_id`。

**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"
}
```

接入操作会调度后台准备工作。当前的 YCloud REST 接口未提供单独的接入状态端点。请求成功响应后，请使用 [GET Get Settings](/api-reference/meta-business-agents/get-settings) 确认电话作用域的资源是否已就绪。如果读取临时失败，请稍作延迟后重试；切勿盲目重复接入操作。

返回 `403` 通常表示产品访问权限或条款接受未完成。后续电话作用域操作中返回 `404` 可能表示 Phone Number ID 不正确，或者同一个 YCloud 租户名下未拥有活跃的 Public API Agent 绑定。

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

在测试人工转接工作流之前，请先在 Agent 配置中定义这些消息和时间间隔。

**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` | 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](/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."
  }'
```

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

## 添加常见问题 (FAQ)

每个 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` | 是 | Agent 应使用的准确答案。 |
| `metadata` | 否 | 与 FAQ 一同保留的字符串键值对元数据。 |
| `id` | 仅响应 | 用于获取、更新或删除 FAQ 的标识符。 |
| `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."
  }'
```

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

## 添加网站和文件

仅在网站和文件的内容为最新且适合用于回答客户时使用它们。

**网站 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` | 可选 | 需要显式选择时的智能体 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` 和字符串元数据。

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

## 添加 UI 技能

UI 技能控制智能体可以呈现哪些富媒体 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 技能的显示标题。 |
| `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](/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` | 对 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](/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` | 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` 表示不进行转换。更新时，这三种输入存在差异：

```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="/zh/documentation/meta-business-agent/test-and-evaluate">
  验证响应和代表性的业务场景。
</Card>


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