Saltar al contenido principal
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 Onboard Agent · GET Get Settings
Conserva el identificador devuelto:
La incorporación programa la preparación en segundo plano. La superficie REST actual de YCloud no ofrece un endpoint independiente para el estado de la incorporación. Tras recibir una respuesta correcta, usa GET 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 las condiciones están incompletos. Un 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.

Añadir un consumidor de prueba a la lista de permitidos

Usa POST /v2/metaBusinessAgents/{entityId}/allowListEntries con exactamente una identidad no nula:
Como alternativa, proporciona consumer_phone_number en formato E.164. La API pública usa la identidad que especifiques; no busca un BSUID a partir del teléfono. Las entradas de teléfono y BSUID tienen IDs independientes y cada una usa uno de los 20 espacios compartidos de WhatsApp. Elimina mediante el ID de la entrada seleccionada. Las respuestas de lista solo requieren id; es posible que una identidad no esté disponible. consumer_instagram_username se acepta únicamente como campo de respuesta opcional, no como funcionalidad de gestión de Instagram.

Configurar el comportamiento de derivación y seguimiento

Define estos mensajes y tiempos como parte de la configuración del agente antes de probar el flujo de derivación. Referencia de la API: GET Get Settings · PUT Replace Settings
followup_interval_in_seconds debe ser uno de los siguientes valores: 0, 300, 900, 1800, 3600, 7200, 28800 o 86400. Cuando handoff.message_selection sea CUSTOM, incluye handoff.message. YCloud solo actualiza 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

Usa la información del negocio para datos estables que apliquen a las consultas generales de los clientes. Referencia de la API: GET Get Business Info · PUT Replace Business Info · DELETE Delete Business Info
El objeto de información del negocio es cerrado. Envía únicamente campos definidos por el esquema de la API de YCloud.

Añadir preguntas frecuentes

Mantén una sola intención de cliente por FAQ. Actualiza o elimina respuestas obsoletas en lugar de añadir duplicados casi idénticos. Referencia de la API: GET List FAQs · POST Create FAQ · GET Get FAQ · PATCH Update FAQ · DELETE Delete FAQ
Usa los endpoints de colección enlazados para listar o crear FAQ, y los endpoints de elemento enlazados para recuperar, actualizar o eliminar una FAQ. Para PATCH, envía tanto question como answer. Meta puede devolver un nuevo id y restablecer created_at a la hora de actualización. Usa el ID devuelto para solicitudes posteriores. Un tiempo de espera agotado o 502 no prueba que la actualización haya fallado; no la reintentes automáticamente ni crees una FAQ de reemplazo.

Añadir sitios web y archivos

Usa sitios web y archivos solo 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 solicitudes aceptan los campos de alcance included_sub_domains, included_url_patterns, excluded_sub_domains, excluded_url_patterns y single_urls. Omite un campo de alcance para dejarlo sin especificar; envía [] para borrarlo. Las respuestas pueden incluir los cinco arrays de alcance, crawl_error, crawl_status, pages_crawled, last_crawled_at y created_at. Una actualización puede devolver un id diferente; usa el ID devuelto para posteriores lecturas, actualizaciones y eliminaciones. No reintentes automáticamente una actualización con un resultado incierto. El rastreo es asíncrono, por lo que una respuesta de creación correcta no significa que todas las páginas se hayan indexado. Sube un archivo como multipart/form-data con una parte llamada file:
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}.
Es posible que las tablas en archivos PDF o CSV no se interpreten 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 conductuales

Las habilidades explican cómo debe gestionar una tarea el agente. El conocimiento explica qué es verdad. Referencia de la API: GET List Skills · POST Create Skill · GET Get Skill · PATCH Update Skill · DELETE Delete Skill
Usa los endpoints de colección enlazados para listar o crear habilidades, y los endpoints de elemento enlazados para recuperar, actualizar o eliminar una. Las respuestas también pueden incluir channel, created_at y metadatos de cadena. Asigna a cada habilidad un único objetivo. Indica cuándo usarla, 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 comercial, 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 conductuales 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
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 solo cambia 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 la paginación mientras paging.next esté presente. Las marcas de tiempo de respuesta son segundos de la época de Unix.

Añade 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 agregues ninguno de estos recursos cuando el conocimiento estático sea suficiente.

Configura 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 name, description, base_url y auth_type son obligatorios para 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 con clave de API, inyecta valores en headers, query_params o body_params. Cada elemento requiere field_name y value no vacíos; prefix es opcional. Debe estar presente al menos un elemento. Las credenciales de cliente OAuth requieren token_url, scopes_to_request, client_id y client_secret. Cuando se proporciona, token_request_content_type debe ser application/x-www-form-urlencoded o application/json. Para mTLS, proporciona texto PEM en client_certificate y client_key; ca_certificate es opcional. Nunca registres en logs los cuerpos de solicitud de credenciales. Usa /connectors para listar o crear conectores. Usa /connectors/{connectorId} para recuperar, actualizar o eliminar uno. Reemplaza las credenciales mediante su subrecurso /credentials/apiKey, /credentials/oauth o /credentials/certificate. Para un conector MCP, llama a /connectors/{connectorId}/refreshMCPTools con el Meta Connector ID devuelto por la API de Connector para solicitar a Meta que vuelva a descubrir sus herramientas. No envíes cuerpo de solicitud. HTTP 200 devuelve el conector actual, pero no siempre significa que el descubrimiento se haya completado correctamente. Comprueba mcp_tool_sync.status: READY significa que el descubrimiento finalizó, PENDING significa que todavía está en curso y ERROR significa que el descubrimiento remoto o el aprovisionamiento fallaron. La operación no tiene clave de idempotencia. No la reintentes automáticamente; después de un tiempo de espera, recupera el conector porque el resultado de la actualización es incierto.

Define 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 Crea y lista herramientas en /connectors/{connectorId}/tools. Obtén, actualiza o elimina una en /tools/{toolId}. Las definiciones de parámetros incluyen un tipo de datos (type), una descripción legible para humanos (description), un indicador de obligatoriedad y un enlace (binding) opcional. Un enlace 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 de conector o herramienta no válidas devuelven HTTP 400 sin enviarse upstream.

Transformar respuestas de herramientas

Un valor de 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 admiten 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:
El campo omitido conserva la transformación actual. Para eliminarla:
Para configurarla:
Las macros de enlace 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 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. Usa 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 comerciales representativos.