> ## 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.

# Onboard and configure

> Create a Meta Business Agent and configure its settings, knowledge, skills, connectors, and tools.

This guide creates the agent and defines its configuration. Onboarding prepares the agent resources; it does not make the agent reply to every customer.

## Onboard the phone number

The request body is optional. Include `catalog_id` only when the agent should use a specific Meta catalog.

**API reference:** [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 '{}'
```

Retain the returned identifier:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "agent_id": "AGENT_ID"
}
```

Onboarding schedules background preparation. The current YCloud REST surface does not provide a separate onboarding-status endpoint. After a successful response, use [GET Get Settings](/api-reference/meta-business-agents/get-settings) to confirm that phone-scoped resources are ready. If a read fails temporarily, retry the read after a short delay; do not blindly repeat onboarding.

A `403` usually means that product access or terms acceptance is incomplete. A `404` on later phone-scoped operations can mean that the Phone Number ID is incorrect or that the same YCloud tenant does not own an active Public API agent binding.

## Configure handoff and follow-up behavior

Define these messages and timings as part of the agent configuration, before testing the handoff workflow.

**API reference:** [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"]
  }'
```

| Field | Meaning |
| - | - |
| `handoff.enabled` | Whether the agent can hand a conversation to a human workflow. |
| `handoff.message_selection` | Handoff message source: `DEFAULT`, `AGENT`, or `CUSTOM`. |
| `handoff.message` | Customer-facing message sent when handoff is triggered. |
| `followup.enabled` | Whether the agent sends a follow-up after inactivity. |
| `followup.followup_interval_in_seconds` | Delay before the follow-up. |
| `followup.message` | Customer-facing follow-up message. |
| `never_say_phrases` | Complete list of phrases the agent must not say. |

`followup_interval_in_seconds` must be one of `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800`, or `86400`. When `handoff.message_selection` is `CUSTOM`, include `handoff.message`.

YCloud updates only the settings included in the request. Omit `never_say_phrases` to preserve the current list. Send an empty array to clear it, or a non-empty array to replace the complete list.

## Configure business information

Use business information for stable facts that apply across customer questions.

**API reference:** [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)

| Field | Meaning |
| - | - |
| `payment_method` | Payment methods and conditions customers should know about. |
| `return_policy` | Return, refund, or exchange policy. |
| `purchase_info` | How customers can purchase, book, or place an order. |
| `delivery_and_shipping` | Delivery areas, methods, fees, and timing. |
| `business_description` | Plain-language description of the business and its offerings. |
| `contact_info.email` | Customer-facing contact email. |
| `contact_info.hours_of_operation` | Human-readable operating or support hours. |
| `contact_info.address` | Customer-facing business 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."
  }'
```

The business information object is closed. Send only fields defined by the YCloud API schema.

## Add frequently asked questions

Keep one customer intent per FAQ. Update or delete stale answers instead of adding near-duplicates.

**API reference:** [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)

| Field | Required | Meaning |
| - | - | - |
| `question` | Yes | Customer question written in natural language. |
| `answer` | Yes | Factual answer the agent should use. |
| `metadata` | No | String-to-string metadata retained with the FAQ. |
| `id` | Response only | Identifier used to retrieve, update, or delete the FAQ. |
| `created_at` | Response only | Creation timestamp. |

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

Use the linked collection endpoints to list or create FAQs, and the linked item endpoints to retrieve, update, or delete one FAQ.

## Add websites and files

Use websites and files only when their content is current and suitable for customer answers.

**Website API reference:** [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)

**File API reference:** [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)

Create a website source with its `url`. Use `/websites/{websiteId}` to retrieve, update, or delete it. Website responses can include `crawl_status`, `pages_crawled`, `last_crawled_at`, and `created_at`. Crawling is asynchronous, so a successful create response does not mean every page has been indexed.

Upload a file as `multipart/form-data` with one part named `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 requires a non-empty original filename and accepts request files up to 100,000,000 bytes. Meta controls final file-type and content acceptance. List files at `/files`; retrieve or delete one at `/files/{fileId}`.

<Warning>
  Tables in PDF or CSV files may not be interpreted reliably. Treat files as retrieval sources and test representative content. Do not assume that the agent can send the source image or file back to a customer.
</Warning>

## Add behavioral skills

Skills explain how the agent should handle a task. Knowledge explains what is true.

**API reference:** [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)

| Field | Limit | Meaning |
| - | - | - |
| `agent_id` | Optional | Agent ID when explicit selection is required. |
| `title` | 64 characters | Lowercase letters, numbers, and hyphens, with no leading or trailing hyphen. |
| `description` | 1,024 characters | When the skill should be used. |
| `skill` | 20,000 characters | Complete behavioral instructions. |
| `id` | Response only | Identifier used to retrieve, update, or delete the skill. |

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

Use the linked collection endpoints to list or create skills, and the linked item endpoints to retrieve, update, or delete one. Responses can also include `channel`, `created_at`, and string metadata.

Give each skill one objective. State when to use it, put mandatory rules before examples, and define what to do when information is missing. Keep volatile facts in business information, FAQs, websites, or files.

## Add UI Skills

UI Skills control which rich WhatsApp components the agent can present. Behavioral skills define how the agent should handle a task.

**API reference:** [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."
  }'
```

| Field | Meaning |
| - | - |
| `title` | Display title for the UI Skill. |
| `component_type` | Rich WhatsApp component the agent can present. |
| `status` | `enabled` or `disabled`. |
| `instruction` | When the agent should use this component. |
| `flow_id` | WhatsApp Flow ID. Required only when `component_type` is `flow`; omit it for every other type. |

Supported component types are `carousel_quick_reply`, `carousel_url`, `cta_url`, `flow`, `image`, `interactive_list`, `interactive_reply_buttons`, `location`, and `location_request`.

The update endpoint changes only `title`, `status`, and `instruction`. Create a new UI Skill if you need a different component type or Flow association. List requests support `before`, `after`, and `limit`. Continue pagination while `paging.next` is present. Response timestamps are Unix epoch seconds.

## Add connectors and tools only when needed

A connector defines an external HTTP service or a remote MCP server. A tool defines one operation the agent can call on that connector. Do not add either resource when static knowledge is sufficient.

### Configure the connector

**Connector API reference:** [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)

**Credential API reference:** [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)

| Field | Meaning |
| - | - |
| `name` | Connector name visible to the agent configuration. |
| `description` | Purpose and boundaries of the external service. |
| `base_url` | HTTP base URL or remote MCP server address. |
| `connector_protocol` | Optional `HTTP` or `MCP`; omission on create defaults to HTTP. The protocol cannot change after creation. |
| `auth_type` | Authentication strategy. |
| `auth_config` | OAuth client-credentials or API-key configuration. |
| `user_auth_injection_config` | Where and how a user credential is injected. |
| `requires_certificate` | Whether the connector expects mTLS credentials. |
| `connection_status` | Returned connector validation state and optional error. |
| `mtls_config` | Returned certificate presence and metadata. |
| `mcp_tool_sync` | Optional nullable discovery metadata: `status=ERROR`, `PENDING`, or `READY`, Unix-second attempt/success timestamps, `fingerprint`, and `tool_count`. |

`name`, `description`, `base_url`, and `auth_type` are required for create and update requests. Standard authentication types are `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY`, and `NONE`. Meta can reject another contract value that is not enabled for the account.

For API-key authentication, inject values into `headers`, `query_params`, or `body_params`. Every item requires non-blank `field_name` and `value`; `prefix` is optional. At least one item must be present.

OAuth client credentials require `token_url`, `scopes_to_request`, `client_id`, and `client_secret`. When supplied, `token_request_content_type` must be `application/x-www-form-urlencoded` or `application/json`. For mTLS, provide PEM text in `client_certificate` and `client_key`; `ca_certificate` is optional. Never log credential request bodies.

Use `/connectors` to list or create connectors. Use `/connectors/{connectorId}` to retrieve, update, or delete one. Replace credentials through its `/credentials/apiKey`, `/credentials/oauth`, or `/credentials/certificate` subresource.

For an MCP connector, call `/connectors/{connectorId}/refreshMCPTools` with the Meta Connector ID returned by the Connector API to ask Meta to rediscover its tools. Send no request body. HTTP `200` returns the current connector, but it does not always mean discovery succeeded. Check `mcp_tool_sync.status`: `READY` means discovery completed, `PENDING` means it is still in progress, and `ERROR` means remote discovery or provisioning failed. The operation has no idempotency key. Do not retry it automatically; after a timeout, retrieve the connector because the refresh outcome is uncertain.

### Define tools

**Tool API reference:** [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)

| Field | Meaning |
| - | - |
| `name` | Tool name used by the agent. |
| `description` | Trigger and expected outcome used for tool selection. |
| `request_definition.method` | `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`. |
| `request_definition.path` | Path relative to `base_url`. |
| `request_definition.path_parameters` | Named path parameter definitions. |
| `request_definition.query_parameters` | Named query parameter definitions. |
| `request_definition.headers` | Named request-header definitions. |
| `request_definition.body` | JSON body fields and required-field list. |
| `user_auth_required` | Whether the operation needs an end-user credential. |
| `transformation_spec` | Optional nullable ordered response transformation. Omit on update to retain it, send `null` to delete it, or send an object to set it. |
| `user_auth_action_config` | How to read token, refresh-token, and expiration values from an authentication action. |

Create and list tools at `/connectors/{connectorId}/tools`. Retrieve, update, or delete one at `/tools/{toolId}`.

Parameter definitions include a data `type`, human-readable `description`, required flag, and optional `binding`. A binding can provide a fixed value, macro, or runtime input.

Create and update requests require `name`, `description`, `request_definition`, and `user_auth_required`. A request definition requires `method` and `path`. A body requires `content_type=application/json` and a `params` object. When supplied, `user_auth_action_config` requires `user_action_tool_type` (`auth` or `refresh`) and `user_auth_token_path`; `expires_at_type` must be `absolute` or `relative_seconds`. Invalid connector or tool definitions return HTTP `400` without being forwarded upstream.

### Transform tool responses

A non-null `transformation_spec` requires `version=1` and `steps`, with at most five ordered steps.
Each step requires `kind`. Optional `target` and `params` accept strings or `null`; `params` contains
a JSON object encoded as a string. A `math` expression supports at most four nested levels.

Supported kinds are `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`, and `truncate`.

On create, omission or `null` means no transformation. On update, these three inputs differ:

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

The omitted field preserves the current transformation. To delete it:

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

To set it:

```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\"]}"}]}}
```

Binding macros support `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`, and
`INSTAGRAM_CONVERSATION_ID`. Accepting an Instagram macro does not enable Instagram entities
or guarantee its value for a WhatsApp consumer.

### Check MCP discovery state

MCP uses the same endpoint and authentication fields. A successful connector response can contain
`mcp_tool_sync.status=ERROR`; this means tool discovery failed. Creating a connector does not
establish that tools are ready. First discovery timing and MCP-specific editing restrictions have
not been verified. Use the refresh operation above when Meta needs to rediscover the connector's tools.

<Card title="Next: Test and evaluate" icon="arrow-right" href="/en/documentation/meta-business-agent/test-and-evaluate">
  Validate responses and representative business scenarios.
</Card>


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