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

# Incorporación y configuración

> Crea un Meta Business Agent y configura sus ajustes, conocimientos, habilidades, conectores y herramientas.

Esta guía crea el agente y define su configuración. La incorporación prepara los recursos del agente; no hace que el agente responda a todos los clientes.

## Incorporar el número de teléfono

El cuerpo de la solicitud es opcional. Incluye `catalog_id` solo cuando el agente deba utilizar un catálogo de Meta específico.

**Referencia de la API:** [POST Incorporar agente](/api-reference/meta-business-agents/onboard-agent) · [GET Obtener configuración](/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 '{}'
```

Conserva el identificador devuelto:

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

La incorporación programa la preparación en segundo plano. La superficie REST actual de YCloud no proporciona un endpoint independiente para el estado de la incorporación. Tras una respuesta exitosa, utiliza [GET Obtener configuración](/api-reference/meta-business-agents/get-settings) para confirmar que los recursos asociados al teléfono estén listos. Si una lectura falla temporalmente, vuelve a intentarlo tras una breve pausa; no repitas la incorporación a ciegas.

Un error `403` suele indicar que el acceso al producto o la aceptación de los términos está incompleta. Un error `404` en operaciones posteriores asociadas al teléfono puede indicar que el Phone Number ID es incorrecto o que el mismo tenant de YCloud no posee una vinculación de agente activa en la Public API.

## Configurar el comportamiento de transferencia y seguimiento

Define estos mensajes y tiempos como parte de la configuración del agente antes de probar el flujo de trabajo de transferencia.

**Referencia de la API:** [GET Obtener configuración](/api-reference/meta-business-agents/get-settings) · [PUT Reemplazar configuración](/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"]
  }'
```

| Campo | Significado |
| - | - |
| `handoff.enabled` | Indica si el agente puede transferir una conversación a un flujo de trabajo humano. |
| `handoff.message_selection` | Origen del mensaje de transferencia: `DEFAULT`, `AGENT` o `CUSTOM`. |
| `handoff.message` | Mensaje visible para el cliente que se envía cuando se activa la transferencia. |
| `followup.enabled` | Indica si el agente envía un mensaje de seguimiento tras un periodo de inactividad. |
| `followup.followup_interval_in_seconds` | Tiempo de espera antes del seguimiento. |
| `followup.message` | Mensaje de seguimiento visible para el cliente. |
| `never_say_phrases` | Lista completa de frases que el agente no debe decir. |

`followup_interval_in_seconds` debe ser uno de los siguientes: `0`, `300`, `900`, `1800`, `3600`, `7200`, `28800` o `86400`. Cuando `handoff.message_selection` sea `CUSTOM`, incluye `handoff.message`.

YCloud actualiza solo los ajustes incluidos en la solicitud. Omite `never_say_phrases` para conservar la lista actual. Envía un array vacío para borrarla, o un array no vacío para reemplazar la lista completa.

## Configurar la información del negocio

Utiliza la información del negocio para datos estables que apliquen a diversas preguntas de los clientes.

**Referencia de la API:** [GET Obtener información del negocio](/api-reference/meta-business-agents/get-business-info) · [PUT Reemplazar información del negocio](/api-reference/meta-business-agents/replace-business-info) · [DELETE Eliminar información del negocio](/api-reference/meta-business-agents/delete-business-info)

| Campo | Significado |
| - | - |
| `payment_method` | Métodos y condiciones de pago que los clientes deben conocer. |
| `return_policy` | Política de devoluciones, reembolsos o cambios. |
| `purchase_info` | Cómo pueden los clientes comprar, reservar o realizar un pedido. |
| `delivery_and_shipping` | Zonas, métodos, tarifas y plazos de entrega. |
| `business_description` | Descripción en lenguaje sencillo del negocio y sus ofertas. |
| `contact_info.email` | Correo electrónico de contacto para los clientes. |
| `contact_info.hours_of_operation` | Horarios de atención o soporte legibles para personas. |
| `contact_info.address` | Dirección del negocio visible para los clientes. |

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

El objeto de información del negocio es cerrado. Envía únicamente los campos definidos por el esquema de la API de YCloud.

## Agregar preguntas frecuentes

Mantén una intención de cliente por FAQ. Actualiza o elimina las respuestas obsoletas en lugar de agregar duplicados casi idénticos.

**Referencia de la API:** [GET Listar FAQs](/api-reference/meta-business-agents/list-faqs) · [POST Crear FAQ](/api-reference/meta-business-agents/create-faq) · [GET Obtener FAQ](/api-reference/meta-business-agents/get-faq) · [PATCH Actualizar FAQ](/api-reference/meta-business-agents/update-faq) · [DELETE Eliminar FAQ](/api-reference/meta-business-agents/delete-faq)

| Campo | Obligatorio | Significado |
| - | - | - |
| `question` | Sí | Pregunta del cliente escrita en lenguaje natural. |
| `answer` | Sí | Respuesta factual que el agente debe utilizar. |
| `metadata` | No | Metadatos de cadena a cadena conservados con la FAQ. |
| `id` | Solo en respuesta | Identificador utilizado para recuperar, actualizar o eliminar la FAQ. |
| `created_at` | Solo en respuesta | Marca de tiempo de creación. |

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

Usa los endpoints de colección enlazados para listar o crear preguntas frecuentes, y los endpoints de elementos enlazados para recuperar, actualizar o eliminar una pregunta frecuente.

## Añadir sitios web y archivos

Usa sitios web y archivos únicamente cuando su contenido esté actualizado y sea adecuado para responder a los clientes.

**Referencia de la API de sitios web:** [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)

**Referencia de la API de archivos:** [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)

Crea una fuente de sitio web con su `url`. Usa `/websites/{websiteId}` para recuperarla, actualizarla o eliminarla. Las respuestas de sitios web pueden incluir `crawl_status`, `pages_crawled`, `last_crawled_at` y `created_at`. El rastreo es asíncrono, por lo que una respuesta de creación exitosa no significa que todas las páginas se hayan indexado.

Sube un archivo como `multipart/form-data` con una parte llamada `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 requiere un nombre de archivo original no vacío y acepta archivos de solicitud de hasta 100 000 000 bytes. Meta controla la aceptación final del tipo de archivo y del contenido. Lista archivos en `/files`; recupera o elimina uno en `/files/{fileId}`.

<Warning>
  Las tablas en archivos PDF o CSV pueden no interpretarse de forma fiable. Trata los archivos como fuentes de recuperación y prueba contenido representativo. No asumas que el agente puede enviar la imagen o el archivo de origen de vuelta al cliente.
</Warning>

## Añadir habilidades de comportamiento

Las habilidades explican cómo el agente debe gestionar una tarea. El conocimiento explica lo que es verdad.

**Referencia de la 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)

| Campo | Límite | Significado |
| - | - | - |
| `agent_id` | Opcional | ID del agente cuando se requiere una selección explícita. |
| `title` | 64 caracteres | Letras minúsculas, números y guiones, sin guion al inicio ni al final. |
| `description` | 1024 caracteres | Cuándo debe utilizarse la habilidad. |
| `skill` | 20 000 caracteres | Instrucciones completas de comportamiento. |
| `id` | Solo respuesta | Identificador utilizado para recuperar, actualizar o eliminar la habilidad. |

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

Usa los endpoints de colección enlazados para listar o crear habilidades, y los endpoints de elementos enlazados para recuperar, actualizar o eliminar una. Las respuestas también pueden incluir `channel`, `created_at` y metadatos de tipo cadena.

Asigna un único objetivo a cada habilidad. Indica cuándo utilizarla, coloca las reglas obligatorias antes de los ejemplos y define qué hacer cuando falte información. Mantén los datos volátiles en la información de la empresa, preguntas frecuentes, sitios web o archivos.

## Añadir habilidades de interfaz de usuario (UI Skills)

Las habilidades de interfaz de usuario (UI Skills) controlan qué componentes enriquecidos de WhatsApp puede presentar el agente. Las habilidades de comportamiento definen cómo debe gestionar una tarea el agente.

**Referencia de la 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."
  }'
```

| Campo | Significado |
| - | - |
| `title` | Título visible para la UI Skill. |
| `component_type` | Componente enriquecido de WhatsApp que el agente puede presentar. |
| `status` | `enabled` o `disabled`. |
| `instruction` | Cuándo debe usar el agente este componente. |
| `flow_id` | ID del WhatsApp Flow. Requerido solo cuando `component_type` es `flow`; omítelo para cualquier otro tipo. |

Los tipos de componentes admitidos son `carousel_quick_reply`, `carousel_url`, `cta_url`, `flow`, `image`, `interactive_list`, `interactive_reply_buttons`, `location` y `location_request`.

El endpoint de actualización modifica únicamente `title`, `status` y `instruction`. Crea una nueva UI Skill si necesitas un tipo de componente o una asociación de Flow diferente. Las solicitudes de listado admiten `before`, `after` y `limit`. Continúa con la paginación mientras `paging.next` esté presente. Las marcas de tiempo en la respuesta son segundos epoch de Unix.

## Añadir conectores y herramientas solo cuando sea necesario

Un conector define un servicio HTTP externo o un servidor MCP remoto. Una herramienta define una operación que el agente puede invocar en ese conector. No añadas ninguno de estos recursos cuando el conocimiento estático sea suficiente.

### Configurar el conector

**Referencia de la API de Connector:** [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)

**Referencia de la API de Credential:** [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)

| Campo | Significado |
| - | - |
| `name` | Nombre del conector visible en la configuración del agente. |
| `description` | Propósito y límites del servicio externo. |
| `base_url` | URL base HTTP o dirección remota del servidor MCP. |
| `connector_protocol` | Opcional: `HTTP` o `MCP`; si se omite en la creación, el valor predeterminado es HTTP. El protocolo no se puede cambiar después de la creación. |
| `auth_type` | Estrategia de autenticación. |
| `auth_config` | Configuración de OAuth client-credentials o de API key. |
| `user_auth_injection_config` | Dónde y cómo se inyecta la credencial de un usuario. |
| `requires_certificate` | Indica si el conector espera credenciales mTLS. |
| `connection_status` | Estado de validación del conector devuelto y error opcional. |
| `mtls_config` | Presencia de certificados devuelta y metadatos. |
| `mcp_tool_sync` | Metadatos de descubrimiento opcionales anulables: `status=ERROR`, `PENDING` o `READY`, marcas de tiempo Unix en segundos de intento/éxito, `fingerprint` y `tool_count`. |

`name`, `description`, `base_url` y `auth_type` son obligatorios para las solicitudes de creación y actualización. Los tipos de autenticación estándar son `OAUTH2_CLIENT_CREDENTIALS`, `API_KEY` y `NONE`. Meta puede rechazar otro valor de contrato que no esté habilitado para la cuenta.

Para la autenticación mediante API key, inyecte valores en `headers`, `query_params` o `body_params`. Cada elemento requiere `field_name` y `value` no vacíos; `prefix` es opcional. Debe haber al menos un elemento presente.

OAuth client credentials requiere `token_url`, `scopes_to_request`, `client_id` y `client_secret`. Cuando se suministra, `token_request_content_type` debe ser `application/x-www-form-urlencoded` o `application/json`. Para mTLS, proporcione texto PEM en `client_certificate` y `client_key`; `ca_certificate` es opcional. Nunca registre los cuerpos de las solicitudes de credenciales.

Use `/connectors` para listar o crear conectores. Use `/connectors/{connectorId}` para recuperar, actualizar o eliminar uno. Reemplace las credenciales a través de su subrecurso `/credentials/apiKey`, `/credentials/oauth` o `/credentials/certificate`.

Para un conector MCP, llame a `/connectors/{connectorId}/refreshMCPTools` con el Connector ID de Meta devuelto por la API de Connector para solicitar a Meta que vuelva a detectar sus herramientas. No envíe ningún cuerpo de solicitud. HTTP `200` devuelve el conector actual, pero esto no siempre significa que el descubrimiento se haya completado con éxito. Verifique `mcp_tool_sync.status`: `READY` significa que el descubrimiento finalizó, `PENDING` significa que aún está en progreso y `ERROR` significa que falló el aprovisionamiento o el descubrimiento remoto. La operación no tiene clave de idempotencia. No la reintente automáticamente; después de un tiempo de espera agotado, recupere el conector porque el resultado de la actualización es incierto.

### Definir herramientas

**Referencia de la API de Tool:** [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)

| Campo | Significado |
| - | - |
| `name` | Nombre de la herramienta utilizado por el agente. |
| `description` | Desencadenador y resultado esperado utilizado para la selección de herramientas. |
| `request_definition.method` | `GET`, `POST`, `PUT`, `DELETE` o `PATCH`. |
| `request_definition.path` | Ruta relativa a `base_url`. |
| `request_definition.path_parameters` | Definiciones de parámetros de ruta con nombre. |
| `request_definition.query_parameters` | Definiciones de parámetros de consulta con nombre. |
| `request_definition.headers` | Definiciones de encabezados de solicitud con nombre. |
| `request_definition.body` | Campos del cuerpo JSON y lista de campos obligatorios. |
| `user_auth_required` | Indica si la operación necesita una credencial del usuario final. |
| `transformation_spec` | Transformación de respuesta ordenada opcional y anulable. Omita en la actualización para conservarla, envíe `null` para eliminarla o envíe un objeto para establecerla. |
| `user_auth_action_config` | Cómo leer los valores de token, refresh-token y expiración de una acción de autenticación. |

Crea y lista herramientas en `/connectors/{connectorId}/tools`. Obtén, actualiza o elimina una en `/tools/{toolId}`.

Las definiciones de parámetros incluyen un `type` de datos, un `description` legible por humanos, un indicador de obligatorio y un `binding` opcional. Una vinculación puede proporcionar un valor fijo, una macro o una entrada en tiempo de ejecución.

Las solicitudes de creación y actualización requieren `name`, `description`, `request_definition` y `user_auth_required`. Una definición de solicitud requiere `method` y `path`. Un cuerpo requiere `content_type=application/json` y un objeto `params`. Cuando se proporciona, `user_auth_action_config` requiere `user_action_tool_type` (`auth` o `refresh`) y `user_auth_token_path`; `expires_at_type` debe ser `absolute` o `relative_seconds`. Las definiciones no válidas de conectores o herramientas devuelven HTTP `400` sin ser reenviadas upstream.

### Transformar respuestas de herramientas

Un `transformation_spec` que no sea nulo requiere `version=1` y `steps`, con un máximo de cinco pasos ordenados.
Cada paso requiere `kind`. Los campos opcionales `target` y `params` aceptan cadenas o `null`; `params` contiene
un objeto JSON codificado como cadena. Una expresión `math` admite un máximo de cuatro niveles anidados.

Los tipos admitidos son `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` y `truncate`.

Al crear, la omisión o `null` significa que no hay transformación. Al actualizar, estas tres entradas difieren:

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

El campo omitido conserva la transformación actual. Para eliminarlo:

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

Para configurarlo:

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

Las macros de vinculación admiten `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` y
`INSTAGRAM_CONVERSATION_ID`. Aceptar una macro de Instagram no habilita las entidades de Instagram
ni garantiza su valor para un consumidor de WhatsApp.

### Comprobar el estado de descubrimiento de MCP

MCP utiliza el mismo endpoint y campos de autenticación. Una respuesta correcta del conector puede contener
`mcp_tool_sync.status=ERROR`; esto significa que el descubrimiento de herramientas falló. Crear un conector no
garantiza que las herramientas estén listas. Los tiempos del primer descubrimiento y las restricciones de edición específicas de MCP
no se han verificado. Utiliza la operación de actualización anterior cuando Meta necesite volver a descubrir las herramientas del conector.

<Card title="Siguiente: Probar y evaluar" icon="arrow-right" href="/es/documentation/meta-business-agent/test-and-evaluate">
  Valida las respuestas y los escenarios empresariales representativos.
</Card>


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