Onboard and configure

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

Retain the returned identifier:

{
  "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 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 · 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"]
  }'

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 · PUT Replace Business Info · DELETE 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.

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 · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE 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.

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 · POST Create Website · GET Get Website · PATCH Update Website · DELETE Delete Website File API reference: GET List Files · POST Upload File · GET Get File · DELETE 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:

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

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.

Add behavioral skills

Skills explain how the agent should handle a task. Knowledge explains what is true. API reference: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE 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.

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

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 · POST Create Connector · GET Get Connector · PATCH Update Connector · POST Refresh MCP Connector Tools · DELETE Delete Connector Credential API reference: PUT Upsert API Key · PUT Upsert OAuth Credentials · PUT Upsert 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 · POST Create Connector Tool · GET Get Connector Tool · PATCH Update Connector Tool · DELETE 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:

{"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:

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

To set it:

{"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.

Next: Test and evaluate

Validate responses and representative business scenarios.

Getting Started

Guides

Endpoints

Webhooks

Onboard and configure

Onboard the phone number

Configure handoff and follow-up behavior

Configure business information

Add frequently asked questions

Add websites and files

Add behavioral skills

Add UI Skills

Add connectors and tools only when needed

Configure the connector

Define tools

Transform tool responses

Check MCP discovery state

Next: Test and evaluate

​Onboard the phone number

​Configure handoff and follow-up behavior

​Configure business information

​Add frequently asked questions

​Add websites and files

​Add behavioral skills

​Add UI Skills

​Add connectors and tools only when needed

​Configure the connector

​Define tools

​Transform tool responses

​Check MCP discovery state

Next: Test and evaluate

Onboard the phone number

Configure handoff and follow-up behavior

Configure business information

Add frequently asked questions

Add websites and files

Add behavioral skills

Add UI Skills

Add connectors and tools only when needed

Configure the connector

Define tools

Transform tool responses

Check MCP discovery state