Incorporar el número de teléfono
El cuerpo de la solicitud es opcional. Incluyecatalog_id solo cuando el agente deba utilizar un catálogo de Meta específico.
Referencia de la API: POST Onboard Agent · GET Get Settings
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
UsaPOST /v2/metaBusinessAgents/{entityId}/allowListEntries con exactamente una identidad no nula:
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 Settingsfollowup_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 InfoAñ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 FAQPATCH, 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 suurl. 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:
/files; recupera o elimina uno en /files/{fileId}.
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 Skillchannel, 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 Certificatename, 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 detransformation_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:
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 contenermcp_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.

