Incorporación y configuración

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 · GET Obtener configuración

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:

{
  "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 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 · PUT Reemplazar configuración

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 · PUT Reemplazar información del negocio · DELETE Eliminar información del negocio

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.

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 · POST Crear FAQ · GET Obtener FAQ · PATCH Actualizar FAQ · DELETE Eliminar 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.

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

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

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.

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

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

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

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

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

Para configurarlo:

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

Siguiente: Probar y evaluar

Valida las respuestas y los escenarios empresariales representativos.

Primeros pasos

Guías

Endpoints

Webhooks

Incorporación y configuración

Incorporar el número de teléfono

Configurar el comportamiento de transferencia y seguimiento

Configurar la información del negocio

Agregar preguntas frecuentes

Añadir sitios web y archivos

Añadir habilidades de comportamiento

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

Añadir conectores y herramientas solo cuando sea necesario

Configurar el conector

Definir herramientas

Transformar respuestas de herramientas

Comprobar el estado de descubrimiento de MCP

Siguiente: Probar y evaluar

​Incorporar el número de teléfono

​Configurar el comportamiento de transferencia y seguimiento

​Configurar la información del negocio

​Agregar preguntas frecuentes

​Añadir sitios web y archivos

​Añadir habilidades de comportamiento

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

​Añadir conectores y herramientas solo cuando sea necesario

​Configurar el conector

​Definir herramientas

​Transformar respuestas de herramientas

​Comprobar el estado de descubrimiento de MCP

Siguiente: Probar y evaluar

Incorporar el número de teléfono

Configurar el comportamiento de transferencia y seguimiento

Configurar la información del negocio

Agregar preguntas frecuentes

Añadir sitios web y archivos

Añadir habilidades de comportamiento

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

Añadir conectores y herramientas solo cuando sea necesario

Configurar el conector

Definir herramientas

Transformar respuestas de herramientas

Comprobar el estado de descubrimiento de MCP